man3/mbsnrtowcs.3

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