lib/libc/locale/mbrtowc.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/mbrtowc.3 250883 2013-05-21 19:59:37Z ed $
  26 .\"
  27 .Dd May 4, 2019
  28 .Dt MBRTOWC 3
  29 .Os
  30 .Sh NAME
  31 .Nm mbrtowc ,
  32 .Nm mbrtowc_l ,
  33 .Nm mbrtoc16 ,
  34 .Nm mbrtoc16_l ,
  35 .Nm mbrtoc32 ,
  36 .Nm mbrtoc32_l
  37 .Nd "convert a character to a wide-character code (restartable)"
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In wchar.h
  42 .Ft size_t
  43 .Fo mbrtowc
  44 .Fa "wchar_t * restrict pc" "const char * restrict s" "size_t n"
  45 .Fa "mbstate_t * restrict ps"
  46 .Fc
  47 .In uchar.h
  48 .Ft size_t
  49 .Fo mbrtoc16
  50 .Fa "char16_t * restrict pc" "const char * restrict s" "size_t n"
  51 .Fa "mbstate_t * restrict ps"
  52 .Fc
  53 .Ft size_t
  54 .Fo mbrtoc32
  55 .Fa "char32_t * restrict pc" "const char * restrict s" "size_t n"
  56 .Fa "mbstate_t * restrict ps"
  57 .Fc
  58 .In xlocale.h
  59 .Ft size_t
  60 .Fo mbrtowc_l
  61 .Fa "wchar_t * restrict pc" "const char * restrict s" "size_t n"
  62 .Fa "mbstate_t * restrict ps" "locale_t locale"
  63 .Fc
  64 .Ft size_t
  65 .Fo mbrtoc16_l
  66 .Fa "char16_t * restrict pc" "const char * restrict s" "size_t n"
  67 .Fa "mbstate_t * restrict ps" "locale_t locale"
  68 .Fc
  69 .Ft size_t
  70 .Fo mbrtoc32_l
  71 .Fa "char32_t * restrict pc" "const char * restrict s" "size_t n"
  72 .Fa "mbstate_t * restrict ps" "locale_t locale"
  73 .Fc
  74 .Sh DESCRIPTION
  75 The
  76 .Fn mbrtowc ,
  77 .Fn mbrtowc_l ,
  78 .Fn mbrtoc16 ,
  79 .Fn mbrtoc16_l ,
  80 .Fn mbrtoc32 ,
  81 and
  82 .Fn mbrtoc32_l
  83 functions inspect at most
  84 .Fa n
  85 bytes pointed to by
  86 .Fa s
  87 to determine the number of bytes needed to complete the next multibyte
  88 character.
  89 If a character can be completed, and
  90 .Fa pc
  91 is not
  92 .Dv NULL ,
  93 the wide character which is represented by
  94 .Fa s
  95 is stored in the
  96 .Vt wchar_t ,
  97 .Vt char16_t
  98 or
  99 .Vt char32_t
 100 it points to.
 101 .Pp
 102 If
 103 .Fa s
 104 is
 105 .Dv NULL ,
 106 these functions behave as if
 107 .Fa pc
 108 was
 109 .Dv NULL ,
 110 .Fa s
 111 was an empty string
 112 .Pq Qq
 113 and
 114 .Fa n
 115 was 1.
 116 .Pp
 117 The
 118 .Vt mbstate_t
 119 argument,
 120 .Fa ps ,
 121 is used to keep track of the shift state.
 122 If it is
 123 .Dv NULL ,
 124 these functions use an internal, static
 125 .Vt mbstate_t
 126 object, which is initialized to the initial conversion state
 127 at program startup.
 128 .Pp
 129 As a single
 130 .Vt char16_t
 131 is not large enough to represent certain multibyte characters, the
 132 .Fn mbrtoc16
 133 function may need to be invoked multiple times to convert a single
 134 multibyte character sequence.
 135 .Pp
 136 The
 137 .Fn mbrtowc_l ,
 138 .Fn mbrtoc16_l ,
 139 and
 140 .Fn mbrtoc32_l
 141 functions take an explicit
 142 .Fa locale
 143 argument, whereas the
 144 .Fn mbrtowc ,
 145 .Fn mbrtoc16 ,
 146 and
 147 .Fn mbrtoc32
 148 functions use the current global or per-thread locale.
 149 .Sh RETURN VALUES
 150 The
 151 .Fn mbrtowc ,
 152 .Fn mbrtowc_l ,
 153 .Fn mbrtoc16 ,
 154 .Fn mbrtoc16_l ,
 155 .Fn mbrtoc32 ,
 156 and
 157 .Fn mbrtoc32_l
 158 functions return:
 159 .Bl -tag -width indent
 160 .It 0
 161 The next
 162 .Fa n
 163 or fewer bytes
 164 represent the null wide character
 165 .Pq Li "L'\e0'" .
 166 .It >0
 167 The next
 168 .Fa n
 169 or fewer bytes represent a valid character, these functions
 170 return the number of bytes used to complete the multibyte character.
 171 .It Po Vt size_t Pc Ns \-1
 172 An encoding error has occurred.
 173 The next
 174 .Fa n
 175 or fewer bytes do not contribute to a valid multibyte character.
 176 .It Po Vt size_t Pc Ns \-2
 177 The next
 178 .Fa n
 179 contribute to, but do not complete, a valid multibyte character sequence,
 180 and all
 181 .Fa n
 182 bytes have been processed.
 183 .El
 184 .Pp
 185 The
 186 .Fn mbrtoc16
 187 and
 188 .Fn mbrtoc16_l
 189 functions also return:
 190 .Bl -tag -width indent
 191 .It Po Vt size_t Pc Ns \-3
 192 The next character resulting from a previous call has been stored.
 193 No bytes from the input have been consumed.
 194 .El
 195 .Sh ERRORS
 196 The
 197 .Fn mbrtowc ,
 198 .Fn mbrtowc_l ,
 199 .Fn mbrtoc16 ,
 200 .Fn mbrtoc16_l ,
 201 .Fn mbrtoc32 ,
 202 and
 203 .Fn mbrtoc32_l
 204 functions will fail if:
 205 .Bl -tag -width Er
 206 .It Bq Er EILSEQ
 207 An invalid multibyte sequence was detected.
 208 .It Bq Er EINVAL
 209 The conversion state is invalid.
 210 .El
 211 .Sh SEE ALSO
 212 .Xr mbtowc 3 ,
 213 .Xr multibyte 3 ,
 214 .Xr setlocale 3 ,
 215 .Xr wcrtomb 3 ,
 216 .Xr xlocale 3
 217 .Sh STANDARDS
 218 The
 219 .Fn mbrtowc ,
 220 .Fn mbrtoc16
 221 and
 222 .Fn mbrtoc32
 223 functions conform to
 224 .St -isoC-2011 .