lib/libc/locale/mbsrtowcs.3

   1 .\" $NetBSD: src/lib/libc/locale/mbsrtowcs.3,v 1.8 2004/01/24 16:58:54 wiz Exp $
   2 .\" $DragonFly: src/lib/libc/locale/mbsrtowcs.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 MBSRTOWCS 3
  30 .Os
  31 .\" ----------------------------------------------------------------------
  32 .Sh NAME
  33 .Nm mbsrtowcs
  34 .Nd converts a multibyte character string to a wide character string \
  35 (restartable)
  36 .\" ----------------------------------------------------------------------
  37 .Sh LIBRARY
  38 .Lb libc
  39 .\" ----------------------------------------------------------------------
  40 .Sh SYNOPSIS
  41 .In wchar.h
  42 .Ft size_t
  43 .Fn mbsrtowcs "wchar_t * restrict pwcs" "const char ** restrict s" "size_t n" \
  44 "mbstate_t * restrict ps"
  45 .\" ----------------------------------------------------------------------
  46 .Sh DESCRIPTION
  47 The
  48 .Fn mbsrtowcs
  49 converts the multibyte character string indirectly pointed to by
  50 .Fa s
  51 to the corresponding wide character string, and stores it in the
  52 array pointed to by
  53 .Fa pwcs .
  54 The conversion stops due to the following reasons:
  55 .Bl -bullet
  56 .It
  57 The conversion reaches a null byte.
  58 In this case, the null byte is also converted.
  59 .It
  60 The
  61 .Fn mbsrtowcs
  62 has already stored
  63 .Fa n
  64 wide characters.
  65 .It
  66 The conversion encounters an invalid character.
  67 .El
  68 .Pp
  69 Each character will be converted as if
  70 .Xr mbrtowc 3
  71 is continuously called.
  72 .Pp
  73 After conversion,
  74 if
  75 .Fa pwcs
  76 is not a
  77 .Dv NULL
  78 pointer,
  79 the pointer object pointed to by
  80 .Fa s
  81 is a
  82 .Dv NULL
  83 pointer (if the conversion is stopped due to reaching a null byte)
  84 or the first byte of the character just after the last character converted.
  85 .Pp
  86 If
  87 .Fa pwcs
  88 is not a
  89 .Dv NULL
  90 pointer and the conversion is stopped due to reaching
  91 a null byte, the
  92 .Fn mbsrtowcs
  93 places the state object pointed to by
  94 .Fa ps
  95 to an initial state after the conversion has taken place.
  96 .Pp
  97 The behaviour of
  98 .Fn mbsrtowcs
  99 is affected by the
 100 .Dv LC_CTYPE
 101 category of the current locale.
 102 .Pp
 103 These are the special cases:
 104 .Bl -tag -width 012345678901
 105 .It "s == NULL || *s == NULL"
 106 Undefined (may cause the program to crash).
 107 .It "pwcs == NULL"
 108 The conversion has taken place, but the resulting wide character string
 109 was discarded.
 110 In this case, the pointer object pointed to by
 111 .Fa s
 112 is not modified and
 113 .Fa n
 114 is ignored.
 115 .It "ps == NULL"
 116 The
 117 .Fn mbsrtowcs
 118 uses its own internal state object to keep the conversion state,
 119 instead of
 120 .Fa ps
 121 mentioned in this manual page.
 122 .Pp
 123 Calling any other functions in
 124 .Lb libc
 125 never changes the internal state of
 126 .Fn mbsrtowcs ,
 127 which is initialized at startup time of the program.
 128 .El
 129 .\" ----------------------------------------------------------------------
 130 .Sh RETURN VALUES
 131 .Fn mbsrtowcs
 132 returns:
 133 .Bl -tag -width 012345678901
 134 .It 0 or positive
 135 The value returned is the number of elements stored in the array
 136 pointed to by
 137 .Fa pwcs ,
 138 except for a terminating null wide character (if any).
 139 If
 140 .Fa pwcs
 141 is not null and the value returned is equal to
 142 .Fa n ,
 143 the wide character string pointed to by
 144 .Fa pwcs
 145 is not null terminated.
 146 If
 147 .Fa pwcs
 148 is a null pointer, the value returned is the number of elements to contain
 149 the whole string converted, except for a terminating null wide character.
 150 .It (size_t)-1
 151 The array indirectly pointed to by
 152 .Fa s
 153 contains a byte sequence forming invalid character.
 154 In this case,
 155 .Fn mbsrtowcs
 156 sets
 157 .Va errno
 158 to indicate the error.
 159 .El
 160 .\" ----------------------------------------------------------------------
 161 .Sh ERRORS
 162 .Fn mbsrtowcs
 163 may cause an error in the following case:
 164 .Bl -tag -width Er
 165 .It Bq Er EILSEQ
 166 The pointer pointed to by
 167 .Fa s
 168 points to an invalid or incomplete multibyte character.
 169 .It Bq Er EINVAL
 170 .Fa ps
 171 points to an invalid or uninitialized mbstate_t object.
 172 .El
 173 .\" ----------------------------------------------------------------------
 174 .Sh SEE ALSO
 175 .Xr mbrtowc 3 ,
 176 .Xr mbstowcs 3 ,
 177 .Xr setlocale 3
 178 .\" ----------------------------------------------------------------------
 179 .Sh STANDARDS
 180 The
 181 .Fn mbsrtowcs
 182 function conforms to
 183 .St -isoC-amd1 .
 184 The restrict qualifier is added at
 185 .St -isoC-99 .