2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
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
13 .TH mbstowcs 3 (date) "Linux man-pages (unreleased)"
15 mbstowcs \- convert a multibyte string to a wide-character string
18 .RI ( libc ", " \-lc )
21 .B #include <stdlib.h>
23 .BI "size_t mbstowcs(wchar_t " dest "[restrict ." n "], \
24 const char *restrict " src ,
36 to a wide-character string starting at
40 wide characters are written to
42 The sequence of characters in the string
44 shall begin in the initial shift state.
45 The conversion can stop for three reasons:
47 An invalid multibyte sequence has been encountered.
53 non-L\[aq]\e0\[aq] wide characters have been stored at
55 In this case, the number of wide characters written to
58 shift state at this point is lost.
60 The multibyte string has been completely converted, including the
61 terminating null character (\[aq]\e0\[aq]).
62 In this case, the number of wide characters written to
64 excluding the terminating null wide character, is returned.
66 The programmer must ensure that there is room for at least
76 is ignored, and the conversion proceeds as
77 above, except that the converted wide characters are not written out to memory,
78 and that no length limit exists.
80 In order to avoid the case 2 above, the programmer should make sure
83 greater than or equal to
84 .IR "mbstowcs(NULL,src,0)+1" .
88 function returns the number of wide characters that make
89 up the converted part of the wide-character string, not including the
90 terminating null wide character.
91 If an invalid multibyte sequence was
96 For an explanation of the terms used in this section, see
102 Interface Attribute Value
107 T} Thread safety MT-Safe
112 provides a better interface to the same
126 The program below illustrates the use of
128 as well as some of the wide character classification functions.
129 An example run is the following:
133 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
134 Length of source string (excluding terminator):
136 6 multibyte characters
138 Wide character string is: Grüße! (6 characters)
149 .\" SRC BEGIN (mbstowcs.c)
159 main(int argc, char *argv[])
161 size_t mbslen; /* Number of multibyte characters in source */
162 wchar_t *wcs; /* Pointer to converted wide character string */
165 fprintf(stderr, "Usage: %s <locale> <string>\en", argv[0]);
169 /* Apply the specified locale. */
171 if (setlocale(LC_ALL, argv[1]) == NULL) {
176 /* Calculate the length required to hold argv[2] converted to
177 a wide character string. */
179 mbslen = mbstowcs(NULL, argv[2], 0);
180 if (mbslen == (size_t) \-1) {
185 /* Describe the source string to the user. */
187 printf("Length of source string (excluding terminator):\en");
188 printf(" %zu bytes\en", strlen(argv[2]));
189 printf(" %zu multibyte characters\en\en", mbslen);
191 /* Allocate wide character string of the desired size. Add 1
192 to allow for terminating null wide character (L\[aq]\e0\[aq]). */
194 wcs = calloc(mbslen + 1, sizeof(*wcs));
200 /* Convert the multibyte character string in argv[2] to a
201 wide character string. */
203 if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
208 printf("Wide character string is: %ls (%zu characters)\en",
211 /* Now do some inspection of the classes of the characters in
212 the wide character string. */
214 for (wchar_t *wp = wcs; *wp != 0; wp++) {
215 printf(" %lc ", (wint_t) *wp);
229 putchar(\[aq]\en\[aq]);