lib/libc/locale/mbrtowc.3

   1 .\" $NetBSD: mbrtowc.3,v 1.7 2006/10/14 07:51:01 wiz Exp $
   2 .\"
   3 .\" Copyright (c)2002 Citrus Project,
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd February 4, 2002
  28 .Dt MBRTOWC 3
  29 .Os
  30 .\" ----------------------------------------------------------------------
  31 .Sh NAME
  32 .Nm mbrtowc
  33 .Nd converts a multibyte character to a wide character (restartable)
  34 .\" ----------------------------------------------------------------------
  35 .Sh LIBRARY
  36 .Lb libc
  37 .\" ----------------------------------------------------------------------
  38 .Sh SYNOPSIS
  39 .In wchar.h
  40 .Ft size_t
  41 .Fn mbrtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" \
  42 "mbstate_t * restrict ps"
  43 .\" ----------------------------------------------------------------------
  44 .Sh DESCRIPTION
  45 The
  46 .Fn mbrtowc
  47 usually converts the multibyte character pointed to by
  48 .Fa s
  49 to a wide character, and stores the wide character
  50 to the wchar_t object pointed to by
  51 .Fa pwc
  52 if
  53 .Fa pwc
  54 is
  55 .Pf non- Dv NULL
  56 and
  57 .Fa s
  58 points to a valid character.
  59 The conversion happens in accordance with, and changes the conversion
  60 state described in the mbstate_t object pointed to by
  61 .Fa ps .
  62 This function may examine at most
  63 .Fa n
  64 bytes of the array beginning from
  65 .Fa s .
  66 .Pp
  67 If
  68 .Fa s
  69 points to a valid character and the character corresponds to a nul wide
  70 character, then the
  71 .Fn mbrtowc
  72 places the mbstate_t object pointed to by
  73 .Fa ps
  74 to an initial conversion state.
  75 .Pp
  76 Unlike
  77 .Xr mbtowc 3 ,
  78 the
  79 .Fn mbrtowc
  80 may accept the byte sequence pointed to by
  81 .Fa s
  82 not forming a complete multibyte character
  83 but which may be part of a valid character.
  84 In this case, this function will accept all such bytes
  85 and save them into the conversion state object pointed to by
  86 .Fa ps .
  87 They will be used at subsequent calls of this function to restart
  88 the conversion suspended.
  89 .Pp
  90 The behaviour of
  91 .Fn mbrtowc
  92 is affected by the
  93 .Dv LC_CTYPE
  94 category of the current locale.
  95 .Pp
  96 These are the special cases:
  97 .Bl -tag -width 012345678901
  98 .It "s == NULL"
  99 .Fn mbrtowc
 100 sets the conversion state object pointed to by
 101 .Fa ps
 102 to an initial state and always returns 0.
 103 Unlike
 104 .Xr mbtowc 3 ,
 105 the value returned does not indicate whether the current encoding of
 106 the locale is state-dependent.
 107 .Pp
 108 In this case,
 109 .Fn mbrtowc
 110 ignores
 111 .Fa pwc
 112 and
 113 .Fa n ,
 114 and is equivalent to the following call:
 115 .Bd -literal -offset indent
 116 mbrtowc(NULL, "", 1, ps);
 117 .Ed
 118 .It "pwc == NULL"
 119 The conversion from a multibyte character to a wide character has
 120 taken place and the conversion state may be affected, but the resulting
 121 wide character is discarded.
 122 .It "ps == NULL"
 123 .Fn mbrtowc
 124 uses its own internal state object to keep the conversion state,
 125 instead of
 126 .Fa ps
 127 mentioned in this manual page.
 128 .Pp
 129 Calling any other functions in
 130 .Lb libc
 131 never changes the internal state of
 132 .Fn mbrtowc ,
 133 which is initialized at startup time of the program.
 134 .El
 135 .\" ----------------------------------------------------------------------
 136 .Sh RETURN VALUES
 137 In the usual cases,
 138 .Fn mbrtowc
 139 returns:
 140 .Bl -tag -width 012345678901
 141 .It 0
 142 The next bytes pointed to by
 143 .Fa s
 144 form a nul character.
 145 .It positive
 146 If
 147 .Fa s
 148 points to a valid character,
 149 .Fn mbrtowc
 150 returns the number of bytes in the character.
 151 .It (size_t)-2
 152 .Fa s
 153 points to a byte sequence which possibly contains part of a valid
 154 multibyte character, but which is incomplete.
 155 When
 156 .Fa n
 157 is at least
 158 .Dv MB_CUR_MAX ,
 159 this case can only occur if the array pointed to by
 160 .Fa s
 161 contains a redundant shift sequence.
 162 .It (size_t)-1
 163 .Fa s
 164 points to an illegal byte sequence which does not form a valid multibyte
 165 character.
 166 In this case,
 167 .Fn mbrtowc
 168 sets
 169 .Va errno
 170 to indicate the error.
 171 .El
 172 .\" ----------------------------------------------------------------------
 173 .Sh ERRORS
 174 .Fn mbrtowc
 175 may cause an error in the following case:
 176 .Bl -tag -width Er
 177 .It Bq Er EILSEQ
 178 .Fa s
 179 points to an invalid or incomplete multibyte character.
 180 .It Bq Er EINVAL
 181 .Fa ps
 182 points to an invalid or uninitialized mbstate_t object.
 183 .El
 184 .\" ----------------------------------------------------------------------
 185 .Sh SEE ALSO
 186 .Xr mbrlen 3 ,
 187 .Xr mbtowc 3 ,
 188 .Xr setlocale 3
 189 .\" ----------------------------------------------------------------------
 190 .Sh STANDARDS
 191 The
 192 .Fn mbrtowc
 193 function conforms to
 194 .St -isoC-amd1 .
 195 The restrict qualifier is added at
 196 .St -isoC-99 .