mbstowcs(3)

1MBSTOWCS(3)                Linux Programmer's Manual               MBSTOWCS(3)
2
3
4

NAME

6       mbstowcs - convert a multibyte string to a wide-character string
7

SYNOPSIS

9       #include <stdlib.h>
10
11       size_t mbstowcs(wchar_t *restrict dest, const char *restrict src,
12                       size_t n);
13

DESCRIPTION

15       If  dest  is  not  NULL, the mbstowcs() function converts the multibyte
16       string src to a wide-character string starting at dest.  At most n wide
17       characters  are  written  to  dest.   The sequence of characters in the
18       string src shall begin in the initial shift state.  The conversion  can
19       stop for three reasons:
20
21       1. An  invalid  multibyte sequence has been encountered.  In this case,
22          (size_t) -1 is returned.
23
24       2. n non-L'\0' wide characters have been stored at dest.  In this case,
25          the  number  of wide characters written to dest is returned, but the
26          shift state at this point is lost.
27
28       3. The multibyte string has been completely  converted,  including  the
29          terminating null character ('\0').  In this case, the number of wide
30          characters written to dest,  excluding  the  terminating  null  wide
31          character, is returned.
32
33       The programmer must ensure that there is room for at least n wide char‐
34       acters at dest.
35
36       If dest is NULL, n is ignored, and the conversion  proceeds  as  above,
37       except  that  the converted wide characters are not written out to mem‐
38       ory, and that no length limit exists.
39
40       In order to avoid the case 2 above, the programmer should make  sure  n
41       is greater than or equal to mbstowcs(NULL,src,0)+1.
42

RETURN VALUE

44       The mbstowcs() function returns the number of wide characters that make
45       up the converted part of the wide-character string, not  including  the
46       terminating  null wide character.  If an invalid multibyte sequence was
47       encountered, (size_t) -1 is returned.
48

ATTRIBUTES

50       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
51       tributes(7).
52
53       ┌────────────────────────────────────────────┬───────────────┬─────────┐
54       │Interface                                   │ Attribute     │ Value   │
55       ├────────────────────────────────────────────┼───────────────┼─────────┤
56       │mbstowcs()                                  │ Thread safety │ MT-Safe │
57       └────────────────────────────────────────────┴───────────────┴─────────┘
58

CONFORMING TO

60       POSIX.1-2001, POSIX.1-2008, C99.
61

NOTES

63       The behavior of mbstowcs() depends on the LC_CTYPE category of the cur‐
64       rent locale.
65
66       The function mbsrtowcs(3) provides a better interface to the same func‐
67       tionality.
68

EXAMPLES

70       The program below illustrates the use of mbstowcs(), as well as some of
71       the wide character classification functions.  An  example  run  is  the
72       following:
73
74           $ ./t_mbstowcs de_DE.UTF-8 Grüße!
75           Length of source string (excluding terminator):
76               8 bytes
77               6 multibyte characters
78
79           Wide character string is: Grüße! (6 characters)
80               G alpha upper
81               r alpha lower
82               ü alpha lower
83               ß alpha lower
84               e alpha lower
85               ! !alpha
86
87   Program source
88
89       #include <wctype.h>
90       #include <locale.h>
91       #include <wchar.h>
92       #include <stdio.h>
93       #include <string.h>
94       #include <stdlib.h>
95
96       int
97       main(int argc, char *argv[])
98       {
99           size_t mbslen;      /* Number of multibyte characters in source */
100           wchar_t *wcs;       /* Pointer to converted wide character string */
101
102           if (argc < 3) {
103               fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);
104               exit(EXIT_FAILURE);
105           }
106
107           /* Apply the specified locale. */
108
109           if (setlocale(LC_ALL, argv[1]) == NULL) {
110               perror("setlocale");
111               exit(EXIT_FAILURE);
112           }
113
114           /* Calculate the length required to hold argv[2] converted to
115              a wide character string. */
116
117           mbslen = mbstowcs(NULL, argv[2], 0);
118           if (mbslen == (size_t) -1) {
119               perror("mbstowcs");
120               exit(EXIT_FAILURE);
121           }
122
123           /* Describe the source string to the user. */
124
125           printf("Length of source string (excluding terminator):\n");
126           printf("    %zu bytes\n", strlen(argv[2]));
127           printf("    %zu multibyte characters\n\n", mbslen);
128
129           /* Allocate wide character string of the desired size.  Add 1
130              to allow for terminating null wide character (L'\0'). */
131
132           wcs = calloc(mbslen + 1, sizeof(*wcs));
133           if (wcs == NULL) {
134               perror("calloc");
135               exit(EXIT_FAILURE);
136           }
137
138           /* Convert the multibyte character string in argv[2] to a
139              wide character string. */
140
141           if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
142               perror("mbstowcs");
143               exit(EXIT_FAILURE);
144           }
145
146           printf("Wide character string is: %ls (%zu characters)\n",
147                   wcs, mbslen);
148
149           /* Now do some inspection of the classes of the characters in
150              the wide character string. */
151
152           for (wchar_t *wp = wcs; *wp != 0; wp++) {
153               printf("    %lc ", (wint_t) *wp);
154
155               if (!iswalpha(*wp))
156                   printf("!");
157               printf("alpha ");
158
159               if (iswalpha(*wp)) {
160                   if (iswupper(*wp))
161                       printf("upper ");
162
163                   if (iswlower(*wp))
164                       printf("lower ");
165               }
166
167               putchar('\n');
168           }
169
170           exit(EXIT_SUCCESS);
171       }
172

COLOPHON

177       This  page  is  part of release 5.13 of the Linux man-pages project.  A
178       description of the project, information about reporting bugs,  and  the
179       latest     version     of     this    page,    can    be    found    at
180       https://www.kernel.org/doc/man-pages/.
181
182
183
184GNU                               2021-03-22                       MBSTOWCS(3)