Debian Codegraph @

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