]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
2 | .\" | |
89e3ffe9 | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
fea681da MK |
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. | |
fe382ebf | 8 | .\" %%%LICENSE_END |
fea681da MK |
9 | .\" |
10 | .\" References consulted: | |
11 | .\" GNU glibc-2 source code and manual | |
12 | .\" Dinkumware C library reference http://www.dinkumware.com/ | |
008f1ecc | 13 | .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
fea681da | 14 | .\" |
9ba01802 | 15 | .TH MBSNRTOWCS 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
fea681da | 16 | .SH NAME |
d0f17b57 | 17 | mbsnrtowcs \- convert a multibyte string to a wide-character string |
fea681da MK |
18 | .SH SYNOPSIS |
19 | .nf | |
20 | .B #include <wchar.h> | |
68e4db0a | 21 | .PP |
fea681da | 22 | .BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src , |
b9f02710 | 23 | .BI " size_t " nms ", size_t " len ", mbstate_t *" ps ); |
fea681da | 24 | .fi |
68e4db0a | 25 | .PP |
7dbff9b4 MK |
26 | .in -4n |
27 | Feature Test Macro Requirements for glibc (see | |
28 | .BR feature_test_macros (7)): | |
29 | .in | |
68e4db0a | 30 | .PP |
7dbff9b4 | 31 | .BR mbsnrtowcs (): |
ea91c3fd MK |
32 | .PD 0 |
33 | .ad l | |
34 | .RS 4 | |
35 | .TP 4 | |
36 | Since glibc 2.10: | |
b0da7b8b | 37 | _POSIX_C_SOURCE\ >=\ 200809L |
ea91c3fd | 38 | .TP |
7dbff9b4 MK |
39 | Before glibc 2.10: |
40 | _GNU_SOURCE | |
ea91c3fd MK |
41 | .RE |
42 | .ad | |
43 | .PD | |
fea681da | 44 | .SH DESCRIPTION |
60a90ecd MK |
45 | The |
46 | .BR mbsnrtowcs () | |
47 | function is like the | |
3a72373c | 48 | .BR mbsrtowcs (3) |
60a90ecd | 49 | function, except that |
40aa0db0 MK |
50 | the number of bytes to be converted, starting at |
51 | .IR *src , | |
9caecea1 MK |
52 | is limited to at most |
53 | .IR nms | |
54 | bytes. | |
fea681da | 55 | .PP |
40aa0db0 MK |
56 | If |
57 | .I dest | |
b437fdd9 | 58 | is not NULL, the |
60a90ecd MK |
59 | .BR mbsnrtowcs () |
60 | function converts at | |
40aa0db0 MK |
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 . | |
c13182ef | 72 | The shift state |
40aa0db0 MK |
73 | .I *ps |
74 | is updated. | |
c13182ef | 75 | The conversion is effectively performed by repeatedly |
657e762d | 76 | calling |
0daa9e92 | 77 | .I "mbrtowc(dest, *src, n, ps)" |
40aa0db0 MK |
78 | where |
79 | .I n | |
80 | is some | |
fea681da | 81 | positive number, as long as this call succeeds, and then incrementing |
40aa0db0 MK |
82 | .I dest |
83 | by one and | |
84 | .I *src | |
85 | by the number of bytes consumed. | |
c13182ef | 86 | The |
fea681da | 87 | conversion can stop for three reasons: |
bce5f0ae | 88 | .IP 1. 3 |
bd0914f3 | 89 | An invalid multibyte sequence has been encountered. |
a8204fda | 90 | In this case, |
40aa0db0 | 91 | .I *src |
7d2cb9d5 | 92 | is left pointing to the invalid multibyte sequence, |
009df872 | 93 | .I (size_t)\ \-1 |
7d2cb9d5 | 94 | is returned, |
40aa0db0 MK |
95 | and |
96 | .I errno | |
97 | is set to | |
98 | .BR EILSEQ . | |
bce5f0ae | 99 | .IP 2. |
40aa0db0 MK |
100 | The |
101 | .I nms | |
102 | limit forces a stop, | |
103 | or | |
104 | .I len | |
d1a71985 | 105 | non-L\(aq\e0\(aq wide characters |
40aa0db0 MK |
106 | have been stored at |
107 | .IR dest . | |
a8204fda | 108 | In this case, |
40aa0db0 MK |
109 | .I *src |
110 | is left pointing to the | |
fea681da | 111 | next multibyte sequence to be converted, and the number of wide characters |
40aa0db0 MK |
112 | written to |
113 | .I dest | |
114 | is returned. | |
bce5f0ae MK |
115 | .IP 3. |
116 | The multibyte string has been completely converted, including the | |
d1a71985 | 117 | terminating null wide character (\(aq\e0\(aq) |
40aa0db0 MK |
118 | (which has the side effect of bringing back |
119 | .I *ps | |
120 | to the | |
c13182ef | 121 | initial state). |
a8204fda | 122 | In this case, |
40aa0db0 MK |
123 | .I *src |
124 | is set to NULL, and the number of wide | |
125 | characters written to | |
126 | .IR dest , | |
e9c23bc6 | 127 | excluding the terminating null wide character, |
fea681da MK |
128 | is returned. |
129 | .PP | |
5b711f5e MK |
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. | |
847e0d88 | 135 | .PP |
40aa0db0 | 136 | If |
51700fd7 | 137 | .IR dest |
40aa0db0 MK |
138 | is NULL, |
139 | .I len | |
140 | is ignored, and the conversion proceeds as | |
fbe183be MK |
141 | above, except that the converted wide characters |
142 | are not written out to memory, | |
fea681da MK |
143 | and that no destination length limit exists. |
144 | .PP | |
40aa0db0 MK |
145 | In both of the above cases, if |
146 | .I ps | |
b437fdd9 | 147 | is NULL, a static anonymous |
7b3a353f MK |
148 | state known only to the |
149 | .BR mbsnrtowcs () | |
150 | function is used instead. | |
fea681da | 151 | .PP |
40aa0db0 MK |
152 | The programmer must ensure that there is room for at least |
153 | .I len | |
154 | wide | |
155 | characters at | |
156 | .IR dest . | |
47297adb | 157 | .SH RETURN VALUE |
60a90ecd MK |
158 | The |
159 | .BR mbsnrtowcs () | |
160 | function returns the number of wide characters | |
d0f17b57 | 161 | that make up the converted part of the wide-character string, |
fbe183be | 162 | not including the terminating null wide character. |
c13182ef | 163 | If an invalid multibyte sequence was |
7d2cb9d5 | 164 | encountered, |
009df872 | 165 | .I (size_t)\ \-1 |
40aa0db0 MK |
166 | is returned, and |
167 | .I errno | |
168 | set to | |
169 | .BR EILSEQ . | |
adad095f ZL |
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 | |
847e0d88 | 182 | .sp 1 |
47297adb | 183 | .SH CONFORMING TO |
d9a8bda4 | 184 | POSIX.1-2008. |
fea681da | 185 | .SH NOTES |
d9bfdb9c | 186 | The behavior of |
60a90ecd | 187 | .BR mbsnrtowcs () |
1274071a MK |
188 | depends on the |
189 | .B LC_CTYPE | |
190 | category of the | |
fea681da MK |
191 | current locale. |
192 | .PP | |
40aa0db0 MK |
193 | Passing NULL as |
194 | .I ps | |
195 | is not multithread safe. | |
47297adb | 196 | .SH SEE ALSO |
e37e3282 | 197 | .BR iconv (3), |
9247e95b MK |
198 | .BR mbrtowc (3) |
199 | .BR mbsinit (3), | |
e37e3282 | 200 | .BR mbsrtowcs (3) |