lib/libc/locale/mbrtowc.3

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