Debian Codegraph @

upstream/debian-unstable/man3/wctomb.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 wctomb 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wctomb \- convert a wide character to a multibyte sequence
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdlib.h>
16 .P
17 .BI "int wctomb(char *" s ", wchar_t " wc );
18 .fi
19 .SH DESCRIPTION
20 If
21 .I s
22 is not NULL,
23 the
24 .BR wctomb ()
25 function converts the wide character
26 .I wc
27 to its multibyte representation and stores it at the beginning of
28 the character array pointed to by
29 .IR s .
30 It updates the shift state, which
31 is stored in a static anonymous variable
32 known only to the
33 .BR wctomb ()
34 function,
35 and returns the length of said multibyte representation,
36 that is, the number of
37 bytes written at
38 .IR s .
39 .P
40 At most
41 .B MB_CUR_MAX
42 bytes will be written at
43 .IR s .
44 The programmer must ensure that there is enough room to store the
45 multibyte sequence at
46 .IR s .
47 .P
48 If
49 .I s
50 is NULL, the
51 .BR wctomb ()
52 function
53 .\" The Dinkumware doc and the Single UNIX specification say this, but
54 .\" glibc doesn't implement this.
55 resets the shift state, known only to this function,
56 to the initial state, and
57 returns nonzero if the encoding has nontrivial shift state,
58 or zero if the encoding is stateless.
59 .SH RETURN VALUE
60 If
61 .I s
62 is not NULL, the
63 .BR wctomb ()
64 function
65 returns the number of bytes
66 that have been written to the byte array at
67 .IR s .
68 If
69 .I wc
70 can not be
71 represented as a multibyte sequence (according
72 to the current locale), \-1 is returned.
73 .P
74 If
75 .I s
76 is NULL, the
77 .BR wctomb ()
78 function returns nonzero if the
79 encoding has nontrivial shift state, or zero if the encoding is stateless.
80 .SH ATTRIBUTES
81 For an explanation of the terms used in this section, see
82 .BR attributes (7).
83 .TS
84 allbox;
85 lbx lb lb
86 l l l.
87 Interface Attribute Value
88 T{
89 .na
90 .nh
91 .BR wctomb ()
92 T} Thread safety MT-Unsafe race
93 .TE
94 .SH VERSIONS
95 The function
96 .BR wcrtomb (3)
97 provides
98 a better interface to the same functionality.
99 .SH STANDARDS
100 C11, POSIX.1-2008.
101 .SH HISTORY
102 POSIX.1-2001, C99.
103 .SH NOTES
104 The behavior of
105 .BR wctomb ()
106 depends on the
107 .B LC_CTYPE
108 category of the
109 current locale.
110 .SH SEE ALSO
111 .BR MB_CUR_MAX (3),
112 .BR mblen (3),
113 .BR mbstowcs (3),
114 .BR mbtowc (3),
115 .BR wcrtomb (3),
116 .BR wcstombs (3)