man3/mbsnrtowcs.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 .\"
  11 .TH mbsnrtowcs 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 mbsnrtowcs \- convert a multibyte string to a wide-character string
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <wchar.h>
  20 .P
  21 .BI "size_t mbsnrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src ,
  22 .BI "                  size_t " nms ", size_t " len \
  23 ", mbstate_t *restrict " ps );
  24 .fi
  25 .P
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .P
  31 .BR mbsnrtowcs ():
  32 .nf
  33     Since glibc 2.10:
  34         _POSIX_C_SOURCE >= 200809L
  35     Before glibc 2.10:
  36         _GNU_SOURCE
  37 .fi
  38 .SH DESCRIPTION
  39 The
  40 .BR mbsnrtowcs ()
  41 function is like the
  42 .BR mbsrtowcs (3)
  43 function, except that
  44 the number of bytes to be converted, starting at
  45 .IR *src ,
  46 is limited to at most
  47 .I nms
  48 bytes.
  49 .P
  50 If
  51 .I dest
  52 is not NULL, the
  53 .BR mbsnrtowcs ()
  54 function converts at
  55 most
  56 .I nms
  57 bytes from the
  58 multibyte string
  59 .I *src
  60 to a wide-character string starting at
  61 .IR dest .
  62 At most
  63 .I len
  64 wide characters are written to
  65 .IR dest .
  66 The shift state
  67 .I *ps
  68 is updated.
  69 The conversion is effectively performed by repeatedly
  70 calling
  71 .I "mbrtowc(dest, *src, n, ps)"
  72 where
  73 .I n
  74 is some
  75 positive number, as long as this call succeeds, and then incrementing
  76 .I dest
  77 by one and
  78 .I *src
  79 by the number of bytes consumed.
  80 The
  81 conversion can stop for three reasons:
  82 .IP \[bu] 3
  83 An invalid multibyte sequence has been encountered.
  84 In this case,
  85 .I *src
  86 is left pointing to the invalid multibyte sequence,
  87 .I (size_t)\ \-1
  88 is returned,
  89 and
  90 .I errno
  91 is set to
  92 .BR EILSEQ .
  93 .IP \[bu]
  94 The
  95 .I nms
  96 limit forces a stop,
  97 or
  98 .I len
  99 non-L\[aq]\e0\[aq] wide characters
 100 have been stored at
 101 .IR dest .
 102 In this case,
 103 .I *src
 104 is left pointing to the
 105 next multibyte sequence to be converted, and the number of wide characters
 106 written to
 107 .I dest
 108 is returned.
 109 .IP \[bu]
 110 The multibyte string has been completely converted, including the
 111 terminating null wide character (\[aq]\e0\[aq])
 112 (which has the side effect of bringing back
 113 .I *ps
 114 to the
 115 initial state).
 116 In this case,
 117 .I *src
 118 is set to NULL, and the number of wide
 119 characters written to
 120 .IR dest ,
 121 excluding the terminating null wide character,
 122 is returned.
 123 .P
 124 According to POSIX.1,
 125 if the input buffer ends with an incomplete character,
 126 it is unspecified whether conversion stops at the end of
 127 the previous character (if any), or at the end of the input buffer.
 128 The glibc implementation adopts the former behavior.
 129 .P
 130 If
 131 .I dest
 132 is NULL,
 133 .I len
 134 is ignored, and the conversion proceeds as
 135 above, except that the converted wide characters
 136 are not written out to memory,
 137 and that no destination length limit exists.
 138 .P
 139 In both of the above cases, if
 140 .I ps
 141 is NULL, a static anonymous
 142 state known only to the
 143 .BR mbsnrtowcs ()
 144 function is used instead.
 145 .P
 146 The programmer must ensure that there is room for at least
 147 .I len
 148 wide
 149 characters at
 150 .IR dest .
 151 .SH RETURN VALUE
 152 The
 153 .BR mbsnrtowcs ()
 154 function returns the number of wide characters
 155 that make up the converted part of the wide-character string,
 156 not including the terminating null wide character.
 157 If an invalid multibyte sequence was
 158 encountered,
 159 .I (size_t)\ \-1
 160 is returned, and
 161 .I errno
 162 set to
 163 .BR EILSEQ .
 164 .SH ATTRIBUTES
 165 For an explanation of the terms used in this section, see
 166 .BR attributes (7).
 167 .TS
 168 allbox;
 169 lb lb lbx
 170 l l l.
 171 Interface       Attribute       Value
 172 T{
 173 .na
 174 .nh
 175 .BR mbsnrtowcs ()
 176 T}      Thread safety   T{
 177 .na
 178 .nh
 179 MT-Unsafe race:mbsnrtowcs/!ps
 180 T}
 181 .TE
 182 .SH STANDARDS
 183 POSIX.1-2008.
 184 .SH NOTES
 185 The behavior of
 186 .BR mbsnrtowcs ()
 187 depends on the
 188 .B LC_CTYPE
 189 category of the
 190 current locale.
 191 .P
 192 Passing NULL as
 193 .I ps
 194 is not multithread safe.
 195 .SH SEE ALSO
 196 .BR iconv (3),
 197 .BR mbrtowc (3),
 198 .BR mbsinit (3),
 199 .BR mbsrtowcs (3)