Format
#include <stdlib.h> size_t mbstowcs(wchar_t *pwc, const char *string, size_t n);
Language Level: ANSI
Threadsafe: Yes.
Description
The mbstowcs() function determines the length of the sequence of the multibyte characters pointed to by string. It then converts the multibyte character string that begins in the initial shift state into a wide character string, and stores the wide characters into the buffer that is pointed to by pwc. A maximum of n wide characters are written.
The behavior of this function is affected by the LC_CTYPE category of the current locale. If the program is compiled with LOCALETYPE(*LOCALE), and the CCSID that is associated with locale is single-byte, all the multibyte characters are assumed to be single-byte, and are converted to wide characters like this: 0xC1 is converted to 0x00C1. If CCSID of the locale is a multibyte CCSID, then if the multibyte character is a single-byte character, it is converted as is above. If the multibyte character is a double-byte character, (characters between shiftout 0x0e and shiftin 0x0f), the double-byte characters are copied directly, stripping off the shiftout and shiftin characters. For example, 0x0e41710f is converted to 0x4171.
If the program is compiled using LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF), the multibyte character string is converted from the CCSID of the locale to UNICODE (13488) or UTF32 (1232) as if iconv() were called.
Return Value
The mbstowcs() function returns the number of wide characters generated, not including any ending null wide characters. If a multibyte character that is not valid is encountered, the function returns (size_t)-1.
If a conversion error occurs, errno may be set to ECONVERT.
Examples that use mbstowcs()
/* This program is compiled with LOCALETYPE(*LOCALEUCS2) and */ /* SYSIFCOPT(*IFSIO) */ #include <stdio.h> #include <stdlib.h> #include <locale.h> #include <wchar.h> #include <errno.h> #define LOCNAME "qsys.lib/JA_JP.locale" #define LOCNAME_EN "qsys.lib/EN_US.locale" int main(void) { int length, sl = 0; char string[10]; char string2[] = "ABC"; wchar_t buffer[10]; memset(string, '\0', 10); string[0] = 0xC1; string[1] = 0x0E; string[2] = 0x41; string[3] = 0x71; string[4] = 0x41; string[5] = 0x72; string[6] = 0x0F; string[7] = 0xC2; /* In this first example we will convert */ /* a multibyte character when the CCSID of locale */ /* associated with LC_CTYPE is 37. */ if (setlocale(LC_ALL, LOCNAME_EN) == NULL) printf("setlocale failed.\n"); length = mbstowcs(buffer, string2, 10); /* In this case length ABC is converted to UNICODE ABC */ /* or 0x004100420043. Length will be 3. */ printf("length = %d\n\n", length); /* Now lets try a multibyte example. We first must set the */ /* locale to a multibyte locale. We choose a locale with */ /* CCSID 5026 */ if (setlocale(LC_ALL, LOCNAME) == NULL) printf("setlocale failed.\n"); length = mbstowcs(buffer, string, 10); /* The buffer now has the value: */ /* 0x004103A103A30042 length is 4 */ printf("length = %d\n\n", length); } /* The output should look like this: length = 3 length = 4 */
/* This program is compiled with LOCALETYPE(*LOCALE) and */ /* SYSIFCOPT(*IFSIO) */ #include <stdio.h> #include <stdlib.h> #include <locale.h> #include <wchar.h> #include <errno.h> #define LOCNAME "qsys.lib/JA_JP.locale" #define LOCNAME_EN "qsys.lib/EN_US.locale" int main(void) { int length, sl = 0; char string[10]; char string2[] = "ABC"; wchar_t buffer[10]; memset(string, '\0', 10); string[0] = 0xC1; string[1] = 0x0E; string[2] = 0x41; string[3] = 0x71; string[4] = 0x41; string[5] = 0x72; string[6] = 0x0F; string[7] = 0xC2; /* In this first example we will convert */ /* a multibyte character when the CCSID of locale */ /* associated with LC_CTYPE is 37. */ if (setlocale(LC_ALL, LOCNAME_EN) == NULL) printf("setlocale failed.\n"); length = mbstowcs(buffer, string2, 10); /* In this case length ABC is converted to */ /* 0x00C100C200C3. Length will be 3. */ printf("length = %d\n\n", length); /* Now lets try a multibyte example. We first must set the * /* locale to a multibyte locale. We choose a locale with /* CCSID 5026 */ if (setlocale(LC_ALL, LOCNAME) == NULL) printf("setlocale failed.\n"); length = mbstowcs(buffer, string, 10); /* The buffer now has the value: */ /* 0x00C14171417200C2 length is 4 */ printf("length = %d\n\n", length); } /* The output should look like this: length = 3 length = 4 */
Related Information
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.