mbstowcs() — Convert a Multibyte String to a Wide Character String
Format
#include <stdlib.h>
size_t mbstowcs(wchar_t *pwc, const char *string, size_t n);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE category of the current locale. This function might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function
See Wide Characters for more information.
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.
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
might
be set to ECONVERT.
Examples
/* 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
*/