lib/libc/locale/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: head/lib/libc/locale/mbsrtowcs.3 140081 2005-01-11 20:50:51Z ru $
  26 .\"
  27 .Dd December 26, 2013
  28 .Dt MBSRTOWCS 3
  29 .Os
  30 .Sh NAME
  31 .Nm mbsrtowcs ,
  32 .Nm mbsrtowcs_l ,
  33 .Nm mbsnrtowcs ,
  34 .Nm mbsnrtowcs_l
  35 .Nd "convert a character string to a wide-character string (restartable)"
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In wchar.h
  40 .Ft size_t
  41 .Fo mbsrtowcs
  42 .Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len"
  43 .Fa "mbstate_t * restrict ps"
  44 .Fc
  45 .Ft size_t
  46 .Fo mbsnrtowcs
  47 .Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t nms"
  48 .Fa "size_t len" "mbstate_t * restrict ps"
  49 .Fc
  50 .In xlocale.h
  51 .Ft size_t
  52 .Fo mbsrtowcs_l
  53 .Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len"
  54 .Fa "mbstate_t * restrict ps" "locale_t locale"
  55 .Fc
  56 .Ft size_t
  57 .Fo mbsnrtowcs_l
  58 .Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t nms"
  59 .Fa "size_t len" "mbstate_t * restrict ps" "locale_t locale"
  60 .Fc
  61 .Sh DESCRIPTION
  62 The
  63 .Fn mbsrtowcs
  64 and
  65 .Fn mbsrtowcs_l
  66 functions convert a sequence of multibyte characters pointed to indirectly by
  67 .Fa src
  68 into a sequence of corresponding wide characters and store at most
  69 .Fa len
  70 of them in the
  71 .Vt wchar_t
  72 array pointed to by
  73 .Fa dst ,
  74 until they encounter a terminating null character
  75 .Pq Li '\e0' .
  76 .Pp
  77 If
  78 .Fa dst
  79 is
  80 .Dv NULL ,
  81 no characters are stored.
  82 .Pp
  83 If
  84 .Fa dst
  85 is not
  86 .Dv NULL ,
  87 the pointer pointed to by
  88 .Fa src
  89 is updated to point to the character after the one that conversion stopped at.
  90 If conversion stops because a null character is encountered,
  91 .Fa *src
  92 is set to
  93 .Dv NULL .
  94 .Pp
  95 The
  96 .Vt mbstate_t
  97 argument,
  98 .Fa ps ,
  99 is used to keep track of the shift state.
 100 If it is
 101 .Dv NULL ,
 102 .Fn mbsrtowcs
 103 and
 104 .Fn mbsrtowcs_l
 105 use an internal, static
 106 .Vt mbstate_t
 107 object, which is initialized to the initial conversion state
 108 at program startup.
 109 .Pp
 110 The
 111 .Fn mbsnrtowcs
 112 and
 113 .Fn mbsnrtowcs_l
 114 functions behave identically to
 115 .Fn mbsrtowcs
 116 and
 117 .Fn mbsrtowcs_l ,
 118 except that conversion stops after reading at most
 119 .Fa nms
 120 bytes from the buffer pointed to by
 121 .Fa src .
 122 .Pp
 123 The
 124 .Fn mbsrtowcs_l
 125 and
 126 .Fn mbsnrtowcs_l
 127 functions take an explicit
 128 .Fa locale
 129 argument, whereas the
 130 .Fn mbsrtowcs
 131 and
 132 .Fn mbsnrtowcs
 133 functions use the current global or per-thread locale.
 134 .Sh RETURN VALUES
 135 The
 136 .Fn mbsrtowcs ,
 137 .Fn mbsrtowcs_l ,
 138 .Fn mbsnrtowcs ,
 139 and
 140 .Fn mbsnrtowcs_l
 141 functions return the number of wide characters stored in
 142 the array pointed to by
 143 .Fa dst
 144 if successful, otherwise they return
 145 .Po Vt size_t Pc Ns \-1 .
 146 .Sh ERRORS
 147 The
 148 .Fn mbsrtowcs ,
 149 .Fn mbsrtowcs_l ,
 150 .Fn mbsnrtowcs ,
 151 and
 152 .Fn mbsnrtowcs_l
 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 mbsrtowcs_l ,
 174 .Fn mbsnrtowcs ,
 175 and
 176 .Fn mbsnrtowcs_l
 177 functions are an extension to the standard.