lib/libc/locale/mbtowc.3

   1 .\" $NetBSD: mbtowc.3,v 1.8 2006/10/16 09:10:29 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 3, 2002
  28 .Dt MBTOWC 3
  29 .Os
  30 .\" ----------------------------------------------------------------------
  31 .Sh NAME
  32 .Nm mbtowc
  33 .Nd converts a multibyte character to a wide character
  34 .\" ----------------------------------------------------------------------
  35 .Sh LIBRARY
  36 .Lb libc
  37 .\" ----------------------------------------------------------------------
  38 .Sh SYNOPSIS
  39 .In stdlib.h
  40 .Ft int
  41 .Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n"
  42 .Sh DESCRIPTION
  43 .Fn mbtowc
  44 usually converts the multibyte character pointed to by
  45 .Fa s
  46 to a wide character, and stores it in the wchar_t object pointed to by
  47 .Fa pwc
  48 if
  49 .Fa pwc
  50 is
  51 .Pf non- Dv NULL
  52 and
  53 .Fa s
  54 points to a valid character.
  55 This function may inspect at most n bytes of the array beginning from
  56 .Fa s .
  57 .Pp
  58 In state-dependent encodings,
  59 .Fa s
  60 may point to the special sequence bytes to change the shift-state.
  61 Although such sequence bytes correspond to no individual
  62 wide-character code,
  63 .Fn mbtowc
  64 changes its own state by the sequence bytes and treats them
  65 as if they are a part of the subsequence multibyte character.
  66 .Pp
  67 Unlike
  68 .Xr mbrtowc 3 ,
  69 the first
  70 .Fa n
  71 bytes pointed to by
  72 .Fa s
  73 need to form an entire multibyte character.
  74 Otherwise, this function causes an error.
  75 .Pp
  76 Calling any other functions in
  77 .Lb libc
  78 never changes the internal state of
  79 .Fn mbtowc ,
  80 except for calling
  81 .Xr setlocale 3
  82 with changing the
  83 .Dv LC_CTYPE
  84 category of the current locale.
  85 Such
  86 .Xr setlocale 3
  87 call causes the internal state of this function to be indeterminate.
  88 .Pp
  89 The behaviour of
  90 .Fn mbtowc
  91 is affected by the
  92 .Dv LC_CTYPE
  93 category of the current locale.
  94 .Pp
  95 There are special cases:
  96 .Bl -tag -width 012345678901
  97 .It s == NULL
  98 .Fn mbtowc
  99 initializes its own internal state to an initial state, and
 100 determines whether the current encoding is state-dependent.
 101 This function returns 0 if the encoding is state-independent,
 102 otherwise non-zero.
 103 In this case,
 104 .Fa pwc
 105 is completely ignored.
 106 .It pwc == NULL
 107 .Fn mbtowc
 108 executes the conversion as if
 109 .Fa pwc
 110 is non-NULL, but a result of the conversion is discarded.
 111 .It n == 0
 112 In this case,
 113 the first
 114 .Fa n
 115 bytes of the array pointed to by
 116 .Fa s
 117 never form a complete character.
 118 Thus, the
 119 .Fn mbtowc
 120 always fails.
 121 .El
 122 .\" ----------------------------------------------------------------------
 123 .Sh RETURN VALUES
 124 Normally, the
 125 .Fn mbtowc
 126 returns:
 127 .Bl -tag -width 012345678901
 128 .It 0
 129 .Fa s
 130 points to a nul byte
 131 .Pq Sq \e0 .
 132 .It positive
 133 Number of bytes for the valid multibyte character pointed to by
 134 .Fa s .
 135 There are no cases that the value returned is greater than
 136 the value of the
 137 .Dv MB_CUR_MAX
 138 macro.
 139 .It -1
 140 .Fa s
 141 points to an invalid or an incomplete multibyte character.
 142 The
 143 .Fn mbtowc
 144 also sets
 145 .Va errno
 146 to indicate the error.
 147 .El
 148 .Pp
 149 When
 150 .Fa s
 151 is equal to
 152 .Dv NULL ,
 153 .Fn mbtowc
 154 returns:
 155 .Bl -tag -width 0123456789
 156 .It 0
 157 The current encoding is state-independent.
 158 .It non-zero
 159 The current encoding is state-dependent.
 160 .El
 161 .\" ----------------------------------------------------------------------
 162 .Sh ERRORS
 163 .Fn mbtowc
 164 may cause an error in the following case:
 165 .Bl -tag -width Er
 166 .It Bq Er EILSEQ
 167 .Fa s
 168 points to an invalid or incomplete multibyte character.
 169 .El
 170 .\" ----------------------------------------------------------------------
 171 .Sh SEE ALSO
 172 .Xr mblen 3 ,
 173 .Xr mbrtowc 3 ,
 174 .Xr setlocale 3
 175 .\" ----------------------------------------------------------------------
 176 .Sh STANDARDS
 177 The
 178 .Fn mbtowc
 179 function conforms to
 180 .St -ansiC .
 181 The restrict qualifier is added at
 182 .St -isoC-99 .