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