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