man3/mbsrtowcs.3

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