Debian Codegraph @

upstream/debian-trixie/man3/wcsrtombs.3

raw
1 '\" t
2 .\" Copyright (c) Bruno Haible <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .\" References consulted:
7 .\" GNU glibc-2 source code and manual
8 .\" Dinkumware C library reference http://www.dinkumware.com/
9 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
10 .\" ISO/IEC 9899:1999
11 .\"
12 .TH wcsrtombs 3 2024-06-15 "Linux man-pages 6.9.1"
13 .SH NAME
14 wcsrtombs \- convert a wide-character string to a multibyte string
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <wchar.h>
21 .P
22 .BI "size_t wcsrtombs(char " dest "[restrict ." len "], \
23 const wchar_t **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,
30 the
31 .BR wcsrtombs ()
32 function converts
33 the wide-character string
34 .I *src
35 to a multibyte string starting at
36 .IR dest .
37 At most
38 .I len
39 bytes are written to
40 .IR dest .
41 The shift state
42 .I *ps
43 is updated.
44 The conversion is effectively performed by repeatedly
45 calling
46 .IR "wcrtomb(dest, *src, ps)" ,
47 as long as this call succeeds,
48 and then incrementing
49 .I dest
50 by the
51 number of bytes written and
52 .I *src
53 by one.
54 The conversion can stop for three reasons:
55 .IP \[bu] 3
56 A wide character has been encountered that can not be represented as a
57 multibyte sequence (according to the current locale).
58 In this case,
59 .I *src
60 is left pointing to the invalid wide character,
61 .I (size_t)\ \-1
62 is returned,
63 and
64 .I errno
65 is set to
66 .BR EILSEQ .
67 .IP \[bu]
68 The length limit forces a stop.
69 In this case,
70 .I *src
71 is left pointing
72 to the next wide character to be converted,
73 and the number of bytes written to
74 .I dest
75 is returned.
76 .IP \[bu]
77 The wide-character string has been completely converted, including the
78 terminating null wide character (L\[aq]\[rs]0\[aq]),
79 which has the side effect of bringing back
80 .I *ps
81 to the initial state.
82 In this case,
83 .I *src
84 is set to NULL, and the number
85 of bytes written to
86 .IR dest ,
87 excluding the terminating null byte (\[aq]\[rs]0\[aq]),
88 is returned.
89 .P
90 If
91 .I dest
92 is NULL,
93 .I len
94 is ignored,
95 and the conversion proceeds as above, except that the converted bytes
96 are not written out to memory, and that
97 no length limit exists.
98 .P
99 In both of the above cases,
100 if
101 .I ps
102 is NULL, a static anonymous
103 state known only to the
104 .BR wcsrtombs ()
105 function is used instead.
106 .P
107 The programmer must ensure that there is room for at least
108 .I len
109 bytes
110 at
111 .IR dest .
112 .SH RETURN VALUE
113 The
114 .BR wcsrtombs ()
115 function returns
116 the number of bytes that make up the
117 converted part of multibyte sequence,
118 not including the terminating null byte.
119 If a wide character was encountered
120 which could not be converted,
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 .TS
130 allbox;
131 lb lb lbx
132 l l l.
133 Interface Attribute Value
134 T{
135 .na
136 .nh
137 .BR wcsrtombs ()
138 T} Thread safety T{
139 .na
140 .nh
141 MT-Unsafe race:wcsrtombs/!ps
142 T}
143 .TE
144 .SH STANDARDS
145 C11, POSIX.1-2008.
146 .SH HISTORY
147 POSIX.1-2001, C99.
148 .SH NOTES
149 The behavior of
150 .BR wcsrtombs ()
151 depends on the
152 .B LC_CTYPE
153 category of the
154 current locale.
155 .P
156 Passing NULL as
157 .I ps
158 is not multithread safe.
159 .SH SEE ALSO
160 .BR iconv (3),
161 .BR mbsinit (3),
162 .BR wcrtomb (3),
163 .BR wcsnrtombs (3),
164 .BR wcstombs (3)