1MBSTOWCS(3) Linux Programmer's Manual MBSTOWCS(3)
2
6 mbstowcs - convert a multibyte string to a wide-character string
7
9 #include <stdlib.h>
10 size_t mbstowcs(wchar_t *dest, const char *src, size_t n);
12
14 If dest is not NULL, the mbstowcs() function converts the multibyte
15 string src to a wide-character string starting at dest. At most n wide
16 characters are written to dest. The sequence of characters in the
17 string src shall begin in the initial shift state. The conversion can
18 stop for three reasons:
19 1. An invalid multibyte sequence has been encountered. In this case,
21 (size_t) -1 is returned.
22 2. n non-L'\0' wide characters have been stored at dest. In this case,
24 the number of wide characters written to dest is returned, but the
25 shift state at this point is lost.
26 3. The multibyte string has been completely converted, including the
28 terminating null character ('\0'). In this case, the number of wide
29 characters written to dest, excluding the terminating null wide
30 character, is returned.
31 The programmer must ensure that there is room for at least n wide char‐
33 acters at dest.
34 If dest is NULL, n is ignored, and the conversion proceeds as above,
36 except that the converted wide characters are not written out to mem‐
37 ory, and that no length limit exists.
38 In order to avoid the case 2 above, the programmer should make sure n
40 is greater than or equal to mbstowcs(NULL,src,0)+1.
41
43 The mbstowcs() function returns the number of wide characters that make
44 up the converted part of the wide-character string, not including the
45 terminating null wide character. If an invalid multibyte sequence was
46 encountered, (size_t) -1 is returned.
47
49 For an explanation of the terms used in this section, see at‐
50 tributes(7).
51 ┌───────────┬───────────────┬─────────┐
53 │Interface │ Attribute │ Value │
54 ├───────────┼───────────────┼─────────┤
55 │mbstowcs() │ Thread safety │ MT-Safe │
56 └───────────┴───────────────┴─────────┘
58 POSIX.1-2001, POSIX.1-2008, C99.
59
61 The behavior of mbstowcs() depends on the LC_CTYPE category of the cur‐
62 rent locale.
63 The function mbsrtowcs(3) provides a better interface to the same func‐
65 tionality.
66
68 The program below illustrates the use of mbstowcs(), as well as some of
69 the wide character classification functions. An example run is the
70 following:
71 $ ./t_mbstowcs de_DE.UTF-8 Grüße!
73 Length of source string (excluding terminator):
74 8 bytes
75 6 multibyte characters
76 Wide character string is: Grüße! (6 characters)
78 G alpha upper
79 r alpha lower
80 ü alpha lower
81 ß alpha lower
82 e alpha lower
83 ! !alpha
84 Program source
86 #include <wctype.h>
88 #include <locale.h>
89 #include <wchar.h>
90 #include <stdio.h>
91 #include <string.h>
92 #include <stdlib.h>
93 int
95 main(int argc, char *argv[])
96 {
97 size_t mbslen; /* Number of multibyte characters in source */
98 wchar_t *wcs; /* Pointer to converted wide character string */
99 if (argc < 3) {
101 fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);
102 exit(EXIT_FAILURE);
103 }
104 /* Apply the specified locale */
106 if (setlocale(LC_ALL, argv[1]) == NULL) {
108 perror("setlocale");
109 exit(EXIT_FAILURE);
110 }
111 /* Calculate the length required to hold argv[2] converted to
113 a wide character string */
114 mbslen = mbstowcs(NULL, argv[2], 0);
116 if (mbslen == (size_t) -1) {
117 perror("mbstowcs");
118 exit(EXIT_FAILURE);
119 }
120 /* Describe the source string to the user */
122 printf("Length of source string (excluding terminator):\n");
124 printf(" %zu bytes\n", strlen(argv[2]));
125 printf(" %zu multibyte characters\n\n", mbslen);
126 /* Allocate wide character string of the desired size. Add 1
128 to allow for terminating null wide character (L'\0'). */
129 wcs = calloc(mbslen + 1, sizeof(*wcs));
131 if (wcs == NULL) {
132 perror("calloc");
133 exit(EXIT_FAILURE);
134 }
135 /* Convert the multibyte character string in argv[2] to a
137 wide character string */
138 if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
140 perror("mbstowcs");
141 exit(EXIT_FAILURE);
142 }
143 printf("Wide character string is: %ls (%zu characters)\n",
145 wcs, mbslen);
146 /* Now do some inspection of the classes of the characters in
148 the wide character string */
149 for (wchar_t *wp = wcs; *wp != 0; wp++) {
151 printf(" %lc ", (wint_t) *wp);
152 if (!iswalpha(*wp))
154 printf("!");
155 printf("alpha ");
156 if (iswalpha(*wp)) {
158 if (iswupper(*wp))
159 printf("upper ");
160 if (iswlower(*wp))
162 printf("lower ");
163 }
164 putchar('\n');
166 }
167 exit(EXIT_SUCCESS);
169 }
170
172 mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)
173
175 This page is part of release 5.10 of the Linux man-pages project. A
176 description of the project, information about reporting bugs, and the
177 latest version of this page, can be found at
178 https://www.kernel.org/doc/man-pages/.
179GNU 2020-11-01 MBSTOWCS(3)