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