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