1 '\" t -*- coding: UTF-8 -*-
2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" and Copyright 2014 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
6 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
12 .\" References consulted:
13 .\" GNU glibc-2 source code and manual
14 .\" Dinkumware C library reference http://www.dinkumware.com/
15 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
18 .TH MBSTOWCS 3 2017-09-15 "GNU" "Linux Programmer's Manual"
20 mbstowcs \- convert a multibyte string to a wide-character string
23 .B #include <stdlib.h>
25 .BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n );
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\\0\(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\\0\(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
105 T} Thread safety MT-Safe
108 POSIX.1-2001, POSIX.1-2008, C99.
119 provides a better interface to the same
122 The program below illustrates the use of
124 as well as some of the wide character classification functions.
125 An example run is the following:
129 $ ./t_mbstowcs de_DE.UTF\-8 Grüße!
130 Length of source string (excluding terminator):
132 6 multibyte characters
134 Wide character string is: Grüße! (6 characters)
154 main(int argc, char *argv[])
156 size_t mbslen; /* Number of multibyte characters in source */
157 wchar_t *wcs; /* Pointer to converted wide character string */
161 fprintf(stderr, "Usage: %s <locale> <string>\\n", argv[0]);
165 /* Apply the specified locale */
167 if (setlocale(LC_ALL, argv[1]) == NULL) {
172 /* Calculate the length required to hold argv[2] converted to
173 a wide character string */
175 mbslen = mbstowcs(NULL, argv[2], 0);
176 if (mbslen == (size_t) \-1) {
181 /* Describe the source string to the user */
183 printf("Length of source string (excluding terminator):\\n");
184 printf(" %zu bytes\\n", strlen(argv[2]));
185 printf(" %zu multibyte characters\\n\\n", mbslen);
187 /* Allocate wide character string of the desired size. Add 1
188 to allow for terminating null wide character (L\(aq\\0\(aq). */
190 wcs = calloc(mbslen + 1, sizeof(wchar_t));
196 /* Convert the multibyte character string in argv[2] to a
197 wide character string */
199 if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) {
204 printf("Wide character string is: %ls (%zu characters)\\n",
207 /* Now do some inspection of the classes of the characters in
208 the wide character string */
210 for (wp = wcs; *wp != 0; wp++) {
211 printf(" %lc ", (wint_t) *wp);
225 putchar(\(aq\\n\(aq);