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