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 .Dd May 21, 2013
  26 .Dt WCRTOMB 3
  27 .Os
  28 .Sh NAME
  29 .Nm wcrtomb ,
  30 .Nm c16rtomb ,
  31 .Nm c32rtomb
  32 .Nd "convert a wide-character code to a character (restartable)"
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In wchar.h
  37 .Ft size_t
  38 .Fn wcrtomb "char * restrict s" "wchar_t c" "mbstate_t * restrict ps"
  39 .In uchar.h
  40 .Ft size_t
  41 .Fn c16rtomb "char * restrict s" "char16_t c" "mbstate_t * restrict ps"
  42 .Ft size_t
  43 .Fn c32rtomb "char * restrict s" "char32_t c" "mbstate_t * restrict ps"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn wcrtomb ,
  47 .Fn c16rtomb
  48 and
  49 .Fn c32rtomb
  50 functions store a multibyte sequence representing the
  51 wide character
  52 .Fa c ,
  53 including any necessary shift sequences, to the
  54 character array
  55 .Fa s ,
  56 storing a maximum of
  57 .Dv MB_CUR_MAX
  58 bytes.
  59 .Pp
  60 If
  61 .Fa s
  62 is
  63 .Dv NULL ,
  64 these functions behave as if
  65 .Fa s
  66 pointed to an internal buffer and
  67 .Fa c
  68 was a null wide character (L'\e0').
  69 .Pp
  70 The
  71 .Ft mbstate_t
  72 argument,
  73 .Fa ps ,
  74 is used to keep track of the shift state.
  75 If it is
  76 .Dv NULL ,
  77 these functions use an internal, static
  78 .Vt mbstate_t
  79 object, which is initialized to the initial conversion state
  80 at program startup.
  81 .Pp
  82 As certain multibyte characters may only be represented by a series of
  83 16-bit characters, the
  84 .Fn c16rtomb
  85 may need to invoked multiple times before a multibyte sequence is
  86 returned.
  87 .Sh RETURN VALUES
  88 These functions return the length (in bytes) of the multibyte sequence
  89 needed to represent
  90 .Fa c ,
  91 or
  92 .Po Vt size_t Pc Ns \-1
  93 if
  94 .Fa c
  95 is not a valid wide character code.
  96 .Sh ERRORS
  97 The
  98 .Fn wcrtomb ,
  99 .Fn c16rtomb
 100 and
 101 .Fn c32rtomb
 102 functions will fail if:
 103 .Bl -tag -width Er
 104 .It Bq Er EILSEQ
 105 An invalid wide character code was specified.
 106 .It Bq Er EINVAL
 107 The conversion state is invalid.
 108 .El
 109 .Sh SEE ALSO
 110 .Xr mbrtowc 3 ,
 111 .Xr multibyte 3 ,
 112 .Xr setlocale 3 ,
 113 .Xr wctomb 3
 114 .Sh STANDARDS
 115 The
 116 .Fn wcrtomb ,
 117 .Fn c16rtomb
 118 and
 119 .Fn c32rtomb
 120 functions conform to
 121 .St -isoC-2011 .