locale/FreeBSD/mbsrtowcs.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: src/lib/libc/locale/mbsrtowcs.3,v 1.6 2005/01/11 20:50:49 ru Exp $
  26 .Dd July 21, 2004
  27 .Dt MBSRTOWCS 3
  28 .Os
  29 .Sh NAME
  30 .Nm mbsnrtowcs ,
  31 .Nm mbsnrtowcs_l ,
  32 .Nm mbsrtowcs ,
  33 .Nm mbsrtowcs_l
  34 .Nd "convert a character string to a wide-character string (restartable)"
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In wchar.h
  39 .Ft size_t
  40 .Fo mbsnrtowcs
  41 .Fa "wchar_t *restrict dst"
  42 .Fa "const char **restrict src"
  43 .Fa "size_t nms"
  44 .Fa "size_t len"
  45 .Fa "mbstate_t *restrict ps"
  46 .Fc
  47 .Ft size_t
  48 .Fo mbsrtowcs
  49 .Fa "wchar_t *restrict dst"
  50 .Fa "const char **restrict src"
  51 .Fa "size_t len"
  52 .Fa "mbstate_t *restrict ps"
  53 .Fc
  54 .In wchar.h
  55 .In xlocale.h
  56 .Ft size_t
  57 .Fo mbsrtowcs_l
  58 .Fa "wchar_t *restrict dst"
  59 .Fa "const char **restrict src"
  60 .Fa "size_t len"
  61 .Fa "mbstate_t *restrict ps"
  62 .Fa "locale_t loc"
  63 .Fc
  64 .Ft size_t
  65 .Fo mbsnrtowcs_l
  66 .Fa "wchar_t *restrict dst"
  67 .Fa "const char **restrict src"
  68 .Fa "size_t nms"
  69 .Fa "size_t len"
  70 .Fa "mbstate_t *restrict ps"
  71 .Fa "locale_t loc"
  72 .Fc
  73 .Sh DESCRIPTION
  74 The
  75 .Fn mbsrtowcs
  76 function converts a sequence of multibyte characters, pointed to indirectly by
  77 .Fa src ,
  78 into a sequence of corresponding wide characters. It stores at most
  79 .Fa len
  80 of them in the
  81 .Vt wchar_t
  82 array pointed to by
  83 .Fa dst ,
  84 until it encounters a terminating null character
  85 .Pq Li '\e0' .
  86 .Pp
  87 If
  88 .Fa dst
  89 is
  90 .Dv NULL ,
  91 no characters are stored.
  92 .Pp
  93 If
  94 .Fa dst
  95 is not
  96 .Dv NULL ,
  97 the pointer pointed to by
  98 .Fa src
  99 is updated to point to the character after the one that conversion stopped at.
 100 If conversion stops because a null character is encountered,
 101 .Fa *src
 102 is set to
 103 .Dv NULL .
 104 .Pp
 105 The
 106 .Vt mbstate_t
 107 argument,
 108 .Fa ps ,
 109 is used to keep track of the shift state.
 110 If it is
 111 .Dv NULL ,
 112 .Fn mbsrtowcs
 113 uses an internal, static
 114 .Vt mbstate_t
 115 object, which is initialized to the initial conversion state
 116 at program startup.
 117 .Pp
 118 The
 119 .Fn mbsnrtowcs
 120 function behaves identically to
 121 .Fn mbsrtowcs ,
 122 except that conversion stops after reading at most
 123 .Fa nms
 124 bytes from the buffer pointed to by
 125 .Fa src .
 126 .Pp
 127 While the
 128 .Fn mbsrtowcs
 129 and
 130 .Fn mbsnrtowcs
 131 functions use the current locale, the
 132 .Fn mbsrtowcs_l
 133 and
 134 .Fn mbsnrtowcs_l
 135 functions may be passed locales directly. See
 136 .Xr xlocale 3
 137 for more information.
 138 .Sh RETURN VALUES
 139 The
 140 .Fn mbsrtowcs
 141 and
 142 .Fn mbsnrtowcs
 143 functions return the number of wide characters stored in
 144 the array pointed to by
 145 .Fa dst
 146 if successful, otherwise it returns
 147 .Po Vt size_t Pc Ns \-1 .
 148 .Sh ERRORS
 149 The
 150 .Fn mbsrtowcs
 151 and
 152 .Fn mbsnrtowcs
 153 functions will fail if:
 154 .Bl -tag -width Er
 155 .It Bq Er EILSEQ
 156 An invalid multibyte character sequence was encountered.
 157 .It Bq Er EINVAL
 158 The conversion state is invalid.
 159 .El
 160 .Sh SEE ALSO
 161 .Xr mbrtowc 3 ,
 162 .Xr mbstowcs 3 ,
 163 .Xr multibyte 3 ,
 164 .Xr wcsrtombs 3 ,
 165 .Xr xlocale 3
 166 .Sh STANDARDS
 167 The
 168 .Fn mbsrtowcs
 169 function conforms to
 170 .St -isoC-99 .
 171 .Pp
 172 The
 173 .Fn mbsnrtowcs
 174 function is an extension to the standard.