Debian Codegraph @

upstream/debian-unstable/man3/wcstombs.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 wcstombs 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wcstombs \- 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 <stdlib.h>
16 .P
17 .BR "size_t wcstombs(" "size_t dsize;"
18 .BI " char " dest "[restrict " dsize "], const wchar_t *restrict " src ,
19 .BI " size_t " dsize );
20 .fi
21 .SH DESCRIPTION
22 If
23 .I dest
24 is not NULL, the
25 .BR wcstombs ()
26 function converts
27 the wide-character string
28 .I src
29 to a multibyte string starting at
30 .IR dest .
31 At most
32 .I dsize
33 bytes are written to
34 .IR dest .
35 The sequence of characters placed in
36 .I dest
37 begins in the initial shift state.
38 The conversion can stop for three reasons:
39 .IP \[bu] 3
40 A wide character has been encountered that can not be represented as a
41 multibyte sequence (according to the current locale).
42 In this case,
43 .I (size_t)\ \-1
44 is returned.
45 .IP \[bu]
46 The length limit forces a stop.
47 In this case, the number of bytes written to
48 .I dest
49 is returned, but the shift state at this point is lost.
50 .IP \[bu]
51 The wide-character string has been completely converted, including the
52 terminating null wide character (L\[aq]\[rs]0\[aq]).
53 In this case, the conversion ends in the initial shift state.
54 The number of bytes written to
55 .IR dest ,
56 excluding the terminating null byte (\[aq]\[rs]0\[aq]), is returned.
57 .P
58 The programmer must ensure that there is room for at least
59 .I dsize
60 bytes
61 at
62 .IR dest .
63 .P
64 If
65 .I dest
66 is NULL,
67 .I dsize
68 is ignored, and the conversion proceeds as
69 above, except that the converted bytes are not written out to memory,
70 and no length limit exists.
71 .P
72 In order to avoid the case 2 above, the programmer should make sure
73 .I dsize
74 is greater than or equal to
75 .IR "wcstombs(NULL,src,0)+1" .
76 .SH RETURN VALUE
77 The
78 .BR wcstombs ()
79 function returns the number of bytes that make up the
80 converted part of a multibyte sequence,
81 not including the terminating null byte.
82 If a wide character was encountered which could not be
83 converted,
84 .I (size_t)\ \-1
85 is returned.
86 .SH ATTRIBUTES
87 For an explanation of the terms used in this section, see
88 .BR attributes (7).
89 .TS
90 allbox;
91 lbx lb lb
92 l l l.
93 Interface Attribute Value
94 T{
95 .na
96 .nh
97 .BR wcstombs ()
98 T} Thread safety MT-Safe
99 .TE
100 .SH VERSIONS
101 The function
102 .BR wcsrtombs (3)
103 provides a better interface to the same functionality.
104 .SH STANDARDS
105 C11, POSIX.1-2008.
106 .SH HISTORY
107 POSIX.1-2001, C99.
108 .SH NOTES
109 The behavior of
110 .BR wcstombs ()
111 depends on the
112 .B LC_CTYPE
113 category of the
114 current locale.
115 .SH SEE ALSO
116 .BR mblen (3),
117 .BR mbstowcs (3),
118 .BR mbtowc (3),
119 .BR wcsrtombs (3),
120 .BR wctomb (3)