Format
#include <wchar.h>
size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);Language Level: ANSI
Threadsafe:: Yes, if ps is not NULL
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. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function: See Wide Characters for more information.
Description
This function is the restartable version of the mbtowc() function.
If s is a null pointer, the mbrtowc() function determines the number of bytes necessary to enter the initial shift state (zero if encodings are not state-dependent or if the initial conversion state is described). In this situation, the value of the pwc parameter will be ignored and the resulting shift state described will be the initial conversion state.
If s is not a null pointer, the mbrtowc() function determines the number of bytes that are in the multibyte character (and any leading shift sequences) pointed to by s, produces the value of the corresponding multibyte character and if pwc is not a null pointer, stores that value in the object pointed to by pwc. If the corresponding multibyte character is the null wide character, the resulting state will be reset to the initial conversion state.
This function differs from its corresponding internal-state multibyte character function in that it has an extra parameter, ps of type pointer to mbstate_t that points to an object that can completely describe the current conversion state of the associated multibyte character sequence. If ps is NULL, this function uses an internal static variable for the state.
At most, n bytes of the multibyte string are examined.
Return Value
If s is a null pointer, the mbrtowc() function returns the number of bytes necessary to enter the initial shift state. The value returned must be less than the MB_CUR_MAX macro.
If a conversion error occurs, errno might be set to ECONVERT.
If s is not a null pointer, the mbrtowc() function returns one of the following:
Example that uses mbrtowc()
/* 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];
wchar_t buffer[10];
mbstate_t ps = 0;
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. */
/* For single byte cases the state will always */
/* remain in the initial state 0 */
if (setlocale(LC_ALL, LOCNAME_EN) == NULL)
printf("setlocale failed.\n");
length = mbrtowc(buffer, string, MB_CUR_MAX, &ps);
/* In this case length is 1, and C1 is converted 0x00C1 */
printf("length = %d, state = %d\n\n", length, ps);
printf("MB_CUR_MAX: %d\n\n", MB_CUR_MAX);
/* 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 = mbrtowc(buffer, string, MB_CUR_MAX, &ps);
/* The first is single byte so length is 1 and */
/* the state is still the initial state 0. C1 is converted*/
/* to 0x00C1 */
printf("length = %d, state = %d\n\n", length, ps);
printf("MB_CUR_MAX: %d\n\n", MB_CUR_MAX);
sl += length;
length = mbrtowc(&buffer[1], &string[sl], MB_CUR_MAX, &ps);
/* The next character is a mixed byte. Length is 3 to */
/* account for the shiftout 0x0e. State is */
/* changed to double byte state. 0x4171 is copied into */
/* the buffer */
printf("length = %d, state = %d\n\n", length, ps);
sl += length;
length = mbrtowc(&buffer[2], &string[sl], MB_CUR_MAX, &ps);
/* The next character is also a double byte character. */
/* The state is changed to initial state since this was */
/* the last double byte character. Length is 3 to */
/* account for the ending 0x0f shiftin. 0x4172 is copied */
/* into the buffer. */
printf("length = %d, state = %d\n\n", length, ps);
sl += length;
length = mbrtowc(&buffer[3], &string[sl], MB_CUR_MAX, &ps);
/* The next character is single byte so length is 1 and */
/* state remains in initial state. 0xC2 is converted to */
/* 0x00C2. The buffer now has the value: */
/* 0x00C14171417200C2 */
printf("length = %d, state = %d\n\n", length, ps);
}
/* The output should look like this:
length = 1, state = 0
MB_CUR_MAX: 1
length = 1, state = 0
MB_CUR_MAX: 4
length = 3, state = 2
length = 3, state = 0
length = 1, state = 0
*/ Related Information