Debian Codegraph @

upstream/debian-unstable/man3/wcsnrtombs.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH wcsnrtombs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wcsnrtombs \- convert a wide-character string to a multibyte string
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BR "size_t wcsnrtombs(" "size_t dsize;"
18 .BI " char " dest "[restrict " dsize ],
19 .BI " const wchar_t **restrict " src ,
20 .BI " size_t " nwc ", size_t " dsize ", mbstate_t *restrict " ps );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR wcsnrtombs ():
29 .nf
30 Since glibc 2.10:
31 _POSIX_C_SOURCE >= 200809L
32 Before glibc 2.10:
33 _GNU_SOURCE
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR wcsnrtombs ()
38 function is like the
39 .BR wcsrtombs (3)
40 function,
41 except that the number of wide characters to be converted,
42 starting at
43 .IR *src ,
44 is limited to
45 .IR nwc .
46 .P
47 If
48 .I dest
49 is not NULL,
50 the
51 .BR wcsnrtombs ()
52 function converts
53 at most
54 .I nwc
55 wide characters from
56 the wide-character string
57 .I *src
58 to a multibyte string starting at
59 .IR dest .
60 At most
61 .I dsize
62 bytes are written to
63 .IR dest .
64 The shift state
65 .I *ps
66 is updated.
67 The conversion is effectively performed by repeatedly
68 calling
69 .IR "wcrtomb(dest, *src, ps)" ,
70 as long as this call succeeds,
71 and then incrementing
72 .I dest
73 by the
74 number of bytes written and
75 .I *src
76 by one.
77 The conversion can stop for three reasons:
78 .IP \[bu] 3
79 A wide character has been encountered that can not be represented as a
80 multibyte sequence (according to the current locale).
81 In this case,
82 .I *src
83 is left pointing to the invalid wide character,
84 .I (size_t)\ \-1
85 is returned,
86 and
87 .I errno
88 is set to
89 .BR EILSEQ .
90 .IP \[bu]
91 .I nwc
92 wide characters have been
93 converted without encountering a null wide character (L\[aq]\[rs]0\[aq]),
94 or the size limit forces a stop.
95 In this case,
96 .I *src
97 is left pointing
98 to the next wide character to be converted, and the number of bytes written
99 to
100 .I dest
101 is returned.
102 .IP \[bu]
103 The wide-character string has been completely converted, including the
104 terminating null wide character (which has the side effect of bringing back
105 .I *ps
106 to the initial state).
107 In this case,
108 .I *src
109 is set to NULL, and the number
110 of bytes written to
111 .IR dest ,
112 excluding the terminating null byte (\[aq]\[rs]0\[aq]), is
113 returned.
114 .P
115 If
116 .I dest
117 is NULL,
118 .I dsize
119 is ignored,
120 and the conversion proceeds as above,
121 except that the converted bytes are not written out to memory, and that
122 no destination size limit exists.
123 .P
124 In both of the above cases,
125 if
126 .I ps
127 is NULL, a static anonymous
128 state known only to the
129 .BR wcsnrtombs ()
130 function is used instead.
131 .P
132 The programmer must ensure that there is room for at least
133 .I dsize
134 bytes
135 at
136 .IR dest .
137 .SH RETURN VALUE
138 The
139 .BR wcsnrtombs ()
140 function returns
141 the number of bytes that make up the
142 converted part of multibyte sequence,
143 not including the terminating null byte.
144 If a wide character was encountered which
145 could not be converted,
146 .I (size_t)\ \-1
147 is returned, and
148 .I errno
149 set to
150 .BR EILSEQ .
151 .SH ATTRIBUTES
152 For an explanation of the terms used in this section, see
153 .BR attributes (7).
154 .TS
155 allbox;
156 lb lb lbx
157 l l l.
158 Interface Attribute Value
159 T{
160 .na
161 .nh
162 .BR wcsnrtombs ()
163 T} Thread safety T{
164 .na
165 .nh
166 MT-Unsafe race:wcsnrtombs/!ps
167 T}
168 .TE
169 .SH STANDARDS
170 POSIX.1-2008.
171 .SH NOTES
172 The behavior of
173 .BR wcsnrtombs ()
174 depends on the
175 .B LC_CTYPE
176 category of the
177 current locale.
178 .P
179 Passing NULL as
180 .I ps
181 is not multithread safe.
182 .SH SEE ALSO
183 .BR iconv (3),
184 .BR mbsinit (3),
185 .BR wcsrtombs (3)