Debian Codegraph @

upstream/debian-trixie/man3/mbstowcs.3

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