1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
2 .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
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
12 .TH MBSTOWCS 3 2021-03-22 "Linux man-pages (unreleased)"
14 mbstowcs \- convert a multibyte string to a wide-character string
17 .RI ( libc ", " \-lc )
20 .B #include <stdlib.h>
22 .BI "size_t mbstowcs(wchar_t *restrict " dest ", const char *restrict " src ,
34 to a wide-character string starting at
38 wide characters are written to
40 The sequence of characters in the string
42 shall begin in the initial shift state.
43 The conversion can stop for three reasons:
45 An invalid multibyte sequence has been encountered.
51 non-L\(aq\e0\(aq wide characters have been stored at
53 In this case, the number of wide characters written to
56 shift state at this point is lost.
58 The multibyte string has been completely converted, including the
59 terminating null character (\(aq\e0\(aq).
60 In this case, the number of wide characters written to
62 excluding the terminating null wide character, is returned.
64 The programmer must ensure that there is room for at least
74 is ignored, and the conversion proceeds as
75 above, except that the converted wide characters are not written out to memory,
76 and that no length limit exists.
78 In order to avoid the case 2 above, the programmer should make sure
81 greater than or equal to
82 .IR "mbstowcs(NULL,src,0)+1" .
86 function returns the number of wide characters that make
87 up the converted part of the wide-character string, not including the
88 terminating null wide character.
89 If an invalid multibyte sequence was
94 For an explanation of the terms used in this section, see
102 Interface Attribute Value
105 T} Thread safety MT-Safe
111 POSIX.1-2001, POSIX.1-2008, C99.
122 provides a better interface to the same
125 The program below illustrates the use of
127 as well as some of the wide character classification functions.
128 An example run is the following:
132 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
133 Length of source string (excluding terminator):
135 6 multibyte characters
137 Wide character string is: Grüße! (6 characters)
157 main(int argc, char *argv[])
159 size_t mbslen; /* Number of multibyte characters in source */
160 wchar_t *wcs; /* Pointer to converted wide character string */
163 fprintf(stderr, "Usage: %s <locale> <string>\en", argv[0]);
167 /* Apply the specified locale. */
169 if (setlocale(LC_ALL, argv[1]) == NULL) {
174 /* Calculate the length required to hold argv[2] converted to
175 a wide character string. */
177 mbslen = mbstowcs(NULL, argv[2], 0);
178 if (mbslen == (size_t) \-1) {
183 /* Describe the source string to the user. */
185 printf("Length of source string (excluding terminator):\en");
186 printf(" %zu bytes\en", strlen(argv[2]));
187 printf(" %zu multibyte characters\en\en", mbslen);
189 /* Allocate wide character string of the desired size. Add 1
190 to allow for terminating null wide character (L\(aq\e0\(aq). */
192 wcs = calloc(mbslen + 1, sizeof(*wcs));
198 /* Convert the multibyte character string in argv[2] to a
199 wide character string. */
201 if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
206 printf("Wide character string is: %ls (%zu characters)\en",
209 /* Now do some inspection of the classes of the characters in
210 the wide character string. */
212 for (wchar_t *wp = wcs; *wp != 0; wp++) {
213 printf(" %lc ", (wint_t) *wp);
227 putchar(\(aq\en\(aq);