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
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .PP
  22 .BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src ,
  23 .BI "                 size_t " len ", mbstate_t *restrict " ps );
  24 .fi
  25 .SH DESCRIPTION
  26 If
  27 .I dest
  28 is not NULL, the
  29 .BR mbsrtowcs ()
  30 function converts the
  31 multibyte string
  32 .I *src
  33 to a wide-character string starting at
  34 .IR dest .
  35 At most
  36 .I len
  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 len
  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 .PP
  90 If
  91 .I dest
  92 is NULL,
  93 .I len
  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 .PP
  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 .PP
 107 The programmer must ensure that there is room for at least
 108 .I len
 109 wide
 110 characters at
 111 .IR dest .
 112 .SH RETURN VALUE
 113 The
 114 .BR mbsrtowcs ()
 115 function returns the number of wide characters that make
 116 up the converted part of the wide-character string, not including the
 117 terminating null wide character.
 118 If an invalid multibyte sequence was
 119 encountered,
 120 .I (size_t)\ \-1
 121 is returned, and
 122 .I errno
 123 set to
 124 .BR EILSEQ .
 125 .SH ATTRIBUTES
 126 For an explanation of the terms used in this section, see
 127 .BR attributes (7).
 128 .ad l
 129 .nh
 130 .TS
 131 allbox;
 132 lb lb lbx
 133 l l l.
 134 Interface       Attribute       Value
 135 T{
 136 .BR mbsrtowcs ()
 137 T}      Thread safety   T{
 138 MT-Unsafe race:mbsrtowcs/!ps
 139 T}
 140 .TE
 141 .hy
 142 .ad
 143 .sp 1
 144 .SH STANDARDS
 145 POSIX.1-2001, POSIX.1-2008, C99.
 146 .SH NOTES
 147 The behavior of
 148 .BR mbsrtowcs ()
 149 depends on the
 150 .B LC_CTYPE
 151 category of the
 152 current locale.
 153 .PP
 154 Passing NULL as
 155 .I ps
 156 is not multithread safe.
 157 .SH SEE ALSO
 158 .BR iconv (3),
 159 .BR mbrtowc (3),
 160 .BR mbsinit (3),
 161 .BR mbsnrtowcs (3),
 162 .BR mbstowcs (3)