man3/mbsrtowcs.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" References consulted:
   7 .\"   GNU glibc-2 source code and manual
   8 .\"   Dinkumware C library reference http://www.dinkumware.com/
   9 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .TH mbsrtowcs 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 mbsrtowcs \- convert a multibyte string to a wide-character string (restartable)
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .P
  22 .BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." dsize ],
  23 .BI "                 const char **restrict " src ,
  24 .BI "                 size_t " dsize ", mbstate_t *restrict " ps );
  25 .fi
  26 .SH DESCRIPTION
  27 If
  28 .I dest
  29 is not NULL,
  30 convert the
  31 multibyte string
  32 .I *src
  33 to a wide-character string starting at
  34 .IR dest .
  35 At most
  36 .I dsize
  37 wide characters are written to
  38 .IR dest .
  39 The shift state
  40 .I *ps
  41 is updated.
  42 The conversion is effectively performed by repeatedly
  43 calling
  44 .I "mbrtowc(dest, *src, n, ps)"
  45 where
  46 .I n
  47 is some
  48 positive number, as long as this call succeeds, and then incrementing
  49 .I dest
  50 by one and
  51 .I *src
  52 by the number of bytes consumed.
  53 The conversion can stop for three reasons:
  54 .IP \[bu] 3
  55 An invalid multibyte sequence has been encountered.
  56 In this case,
  57 .I *src
  58 is left pointing to the invalid multibyte sequence,
  59 .I (size_t)\ \-1
  60 is returned,
  61 and
  62 .I errno
  63 is set to
  64 .BR EILSEQ .
  65 .IP \[bu]
  66 .I dsize
  67 non-L\[aq]\e0\[aq] wide characters have been stored at
  68 .IR dest .
  69 In this case,
  70 .I *src
  71 is left pointing to the next
  72 multibyte sequence to be converted,
  73 and the number of wide characters written to
  74 .I dest
  75 is returned.
  76 .IP \[bu]
  77 The multibyte string has been completely converted, including the
  78 terminating null wide character (\[aq]\e0\[aq]), which has the side
  79 effect of bringing back
  80 .I *ps
  81 to the
  82 initial state.
  83 In this case,
  84 .I *src
  85 is set to NULL, and the number of wide
  86 characters written to
  87 .IR dest ,
  88 excluding the terminating null wide character, is returned.
  89 .P
  90 If
  91 .I dest
  92 is NULL,
  93 .I dsize
  94 is ignored,
  95 and the conversion proceeds as above,
  96 except that the converted wide characters are not written out to memory,
  97 and that no length limit exists.
  98 .P
  99 In both of the above cases,
 100 if
 101 .I ps
 102 is NULL, a static anonymous
 103 state known only to the
 104 .BR mbsrtowcs ()
 105 function is used instead.
 106 .P
 107 In order to avoid the case 2 above, the programmer should make sure
 108 .I dsize
 109 is
 110 greater than or equal to
 111 .IR "mbsrtowcs(NULL,src,0,ps)+1" .
 112 .P
 113 The programmer must ensure that there is room for at least
 114 .I dsize
 115 wide
 116 characters at
 117 .IR dest .
 118 .P
 119 This function is a restartable version of
 120 .BR mbstowcs (3).
 121 .SH RETURN VALUE
 122 The number of wide characters that make
 123 up the converted part of the wide-character string, not including the
 124 terminating null wide character.
 125 If an invalid multibyte sequence was
 126 encountered,
 127 .I (size_t)\ \-1
 128 is returned, and
 129 .I errno
 130 set to
 131 .BR EILSEQ .
 132 .SH ATTRIBUTES
 133 For an explanation of the terms used in this section, see
 134 .BR attributes (7).
 135 .TS
 136 allbox;
 137 lb lb lbx
 138 l l l.
 139 Interface       Attribute       Value
 140 T{
 141 .na
 142 .nh
 143 .BR mbsrtowcs ()
 144 T}      Thread safety   T{
 145 .na
 146 .nh
 147 MT-Unsafe race:mbsrtowcs/!ps
 148 T}
 149 .TE
 150 .SH STANDARDS
 151 C11, POSIX.1-2008.
 152 .SH HISTORY
 153 POSIX.1-2001, C99.
 154 .SH NOTES
 155 The behavior of
 156 .BR mbsrtowcs ()
 157 depends on the
 158 .B LC_CTYPE
 159 category of the
 160 current locale.
 161 .P
 162 Passing NULL as
 163 .I ps
 164 is not multithread safe.
 165 .SH SEE ALSO
 166 .BR iconv (3),
 167 .BR mbrtowc (3),
 168 .BR mbsinit (3),
 169 .BR mbsnrtowcs (3),
 170 .BR mbstowcs (3)