Debian Codegraph @

upstream/debian-unstable/man3/mbstowcs.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright 2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .TH mbstowcs 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 mbstowcs \- convert a multibyte string to a wide-character string
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .BR "size_t mbstowcs(" "size_t dsize;"
19 .BI " wchar_t " dest "[restrict " dsize "], const char *restrict " src ,
20 .BI " size_t " dsize );
21 .fi
22 .SH DESCRIPTION
23 If
24 .I dest
25 is not NULL,
26 convert the
27 multibyte string
28 .I src
29 to a wide-character string starting at
30 .IR dest .
31 At most
32 .I dsize
33 wide characters are written to
34 .IR dest .
35 The sequence of characters in the string
36 .I src
37 shall begin in the initial shift state.
38 The conversion can stop for three reasons:
39 .IP \[bu] 3
40 An invalid multibyte sequence has been encountered.
41 In this case,
42 .I (size_t)\ \-1
43 is returned.
44 .IP \[bu]
45 .I dsize
46 non-L\[aq]\[rs]0\[aq] wide characters have been stored at
47 .IR dest .
48 In this case, the number of wide characters written to
49 .I dest
50 is returned, but the
51 shift state at this point is lost.
52 .IP \[bu]
53 The multibyte string has been completely converted, including the
54 terminating null character (\[aq]\[rs]0\[aq]).
55 In this case, the number of wide characters written to
56 .IR dest ,
57 excluding the terminating null wide character, is returned.
58 .P
59 If
60 .I dest
61 is NULL,
62 .I dsize
63 is ignored, and the conversion proceeds as
64 above, except that the converted wide characters are not written out to memory,
65 and that no length limit exists.
66 .P
67 In order to avoid the case 2 above, the programmer should make sure
68 .I dsize
69 is
70 greater than or equal to
71 .IR "mbstowcs(NULL,src,0)+1" .
72 .P
73 The programmer must ensure that there is room for at least
74 .I dsize
75 wide
76 characters at
77 .IR dest .
78 .SH RETURN VALUE
79 The number of wide characters that make
80 up the converted part of the wide-character string, not including the
81 terminating null wide character.
82 If an invalid multibyte sequence was
83 encountered,
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 mbstowcs ()
98 T} Thread safety MT-Safe
99 .TE
100 .SH VERSIONS
101 The function
102 .BR mbsrtowcs (3)
103 provides a better interface to the same
104 functionality.
105 .SH STANDARDS
106 C11, POSIX.1-2008.
107 .SH HISTORY
108 POSIX.1-2001, C99.
109 .SH NOTES
110 The behavior of
111 .BR mbstowcs ()
112 depends on the
113 .B LC_CTYPE
114 category of the
115 current locale.
116 .SH EXAMPLES
117 The program below illustrates the use of
118 .BR mbstowcs (),
119 as well as some of the wide character classification functions.
120 An example run is the following:
121 .P
122 .in +4n
123 .EX
124 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
125 Length of source string (excluding terminator):
126 8 bytes
127 6 multibyte characters
128 \&
129 Wide character string is: Grüße! (6 characters)
130 G alpha upper
131 r alpha lower
132 ü alpha lower
133 ß alpha lower
134 e alpha lower
135 ! !alpha
136 .EE
137 .in
138 .SS Program source
139 \&
140 .\" SRC BEGIN (mbstowcs.c)
141 .EX
142 #include <locale.h>
143 #include <stdio.h>
144 #include <stdlib.h>
145 #include <string.h>
146 #include <wchar.h>
147 #include <wctype.h>
148 \&
149 int
150 main(int argc, char *argv[])
151 {
152 size_t mbslen; /* Number of multibyte characters in source */
153 wchar_t *wcs; /* Pointer to converted wide character string */
154 \&
155 if (argc < 3) {
156 fprintf(stderr, "Usage: %s <locale> <string>\[rs]n", argv[0]);
157 exit(EXIT_FAILURE);
158 }
159 \&
160 /* Apply the specified locale. */
161 \&
162 if (setlocale(LC_ALL, argv[1]) == NULL) {
163 perror("setlocale");
164 exit(EXIT_FAILURE);
165 }
166 \&
167 /* Calculate the length required to hold argv[2] converted to
168 a wide character string. */
169 \&
170 mbslen = mbstowcs(NULL, argv[2], 0);
171 if (mbslen == (size_t) \-1) {
172 perror("mbstowcs");
173 exit(EXIT_FAILURE);
174 }
175 \&
176 /* Describe the source string to the user. */
177 \&
178 printf("Length of source string (excluding terminator):\[rs]n");
179 printf(" %zu bytes\[rs]n", strlen(argv[2]));
180 printf(" %zu multibyte characters\[rs]n\[rs]n", mbslen);
181 \&
182 /* Allocate wide character string of the desired size. Add 1
183 to allow for terminating null wide character (L\[aq]\[rs]0\[aq]). */
184 \&
185 wcs = calloc(mbslen + 1, sizeof(*wcs));
186 if (wcs == NULL) {
187 perror("calloc");
188 exit(EXIT_FAILURE);
189 }
190 \&
191 /* Convert the multibyte character string in argv[2] to a
192 wide character string. */
193 \&
194 if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
195 perror("mbstowcs");
196 exit(EXIT_FAILURE);
197 }
198 \&
199 printf("Wide character string is: %ls (%zu characters)\[rs]n",
200 wcs, mbslen);
201 \&
202 /* Now do some inspection of the classes of the characters in
203 the wide character string. */
204 \&
205 for (wchar_t *wp = wcs; *wp != 0; wp++) {
206 printf(" %lc ", (wint_t) *wp);
207 \&
208 if (!iswalpha(*wp))
209 printf("!");
210 printf("alpha ");
211 \&
212 if (iswalpha(*wp)) {
213 if (iswupper(*wp))
214 printf("upper ");
215 \&
216 if (iswlower(*wp))
217 printf("lower ");
218 }
219 \&
220 putchar(\[aq]\[rs]n\[aq]);
221 }
222 \&
223 exit(EXIT_SUCCESS);
224 }
225 .EE
226 .\" SRC END
227 .SH SEE ALSO
228 .BR mblen (3),
229 .BR mbsrtowcs (3),
230 .BR mbtowc (3),
231 .BR wcstombs (3),
232 .BR wctomb (3)