lib/libc/locale/wcrtomb.3

   1 .\" Copyright (c) 2002-2004 Tim J. Robbins
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: head/lib/libc/locale/wcrtomb.3 250883 2013-05-21 19:59:37Z ed $
  26 .\"
  27 .Dd December 26, 2013
  28 .Dt WCRTOMB 3
  29 .Os
  30 .Sh NAME
  31 .Nm wcrtomb ,
  32 .Nm wcrtomb_l ,
  33 .Nm c16rtomb ,
  34 .Nm c32rtomb
  35 .Nd "convert a wide-character code to a character (restartable)"
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In wchar.h
  40 .Ft size_t
  41 .Fn wcrtomb "char * restrict s" "wchar_t c" "mbstate_t * restrict ps"
  42 .In uchar.h
  43 .Ft size_t
  44 .Fn c16rtomb "char * restrict s" "char16_t c" "mbstate_t * restrict ps"
  45 .Ft size_t
  46 .Fn c32rtomb "char * restrict s" "char32_t c" "mbstate_t * restrict ps"
  47 .In xlocale.h
  48 .Ft size_t
  49 .Fn wcrtomb_l "char * restrict s" "wchar_t c" "mbstate_t * restrict ps" "locale_t locale"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn wcrtomb ,
  53 .Fn wcrtomb_l ,
  54 .Fn c16rtomb
  55 and
  56 .Fn c32rtomb
  57 functions store a multibyte sequence representing the
  58 wide character
  59 .Fa c ,
  60 including any necessary shift sequences, to the
  61 character array
  62 .Fa s ,
  63 storing a maximum of
  64 .Dv MB_CUR_MAX
  65 bytes.
  66 .Pp
  67 If
  68 .Fa s
  69 is
  70 .Dv NULL ,
  71 these functions behave as if
  72 .Fa s
  73 pointed to an internal buffer and
  74 .Fa c
  75 was a null wide character (L'\e0').
  76 .Pp
  77 The
  78 .Ft mbstate_t
  79 argument,
  80 .Fa ps ,
  81 is used to keep track of the shift state.
  82 If it is
  83 .Dv NULL ,
  84 these functions use an internal, static
  85 .Vt mbstate_t
  86 object, which is initialized to the initial conversion state
  87 at program startup.
  88 .Pp
  89 As certain multibyte characters may only be represented by a series of
  90 16-bit characters, the
  91 .Fn c16rtomb
  92 may need to invoked multiple times before a multibyte sequence is
  93 returned.
  94 .Pp
  95 The
  96 .Fn wcrtomb_l
  97 function takes an explicit
  98 .Fa locale
  99 argument, whereas the
 100 .Fn wcrtomb
 101 function uses the current global or per-thread locale.
 102 .Sh RETURN VALUES
 103 These functions return the length (in bytes) of the multibyte sequence
 104 needed to represent
 105 .Fa c ,
 106 or
 107 .Po Vt size_t Pc Ns \-1
 108 if
 109 .Fa c
 110 is not a valid wide character code.
 111 .Sh ERRORS
 112 The
 113 .Fn wcrtomb ,
 114 .Fn wcrtomb_l ,
 115 .Fn c16rtomb
 116 and
 117 .Fn c32rtomb
 118 functions will fail if:
 119 .Bl -tag -width Er
 120 .It Bq Er EILSEQ
 121 An invalid wide character code was specified.
 122 .It Bq Er EINVAL
 123 The conversion state is invalid.
 124 .El
 125 .Sh SEE ALSO
 126 .Xr mbrtowc 3 ,
 127 .Xr multibyte 3 ,
 128 .Xr setlocale 3 ,
 129 .Xr wctomb 3 ,
 130 .Xr xlocale 3
 131 .Sh STANDARDS
 132 The
 133 .Fn wcrtomb ,
 134 .Fn c16rtomb
 135 and
 136 .Fn c32rtomb
 137 functions conform to
 138 .St -isoC-2011 .