フォーマット
#include <wchar.h> size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
言語レベル: ANSI
スレッド・セーフ: はい (ps が NULL 以外の場合)。
ロケール依存: この関数の振る舞いは、 現行ロケールの LC_CTYPE カテゴリーの影響を受ける可能性があります。 この関数は、LOCALETYPE(*LOCALEUCS2) または LOCALETYPE(*LOCALEUTF) をコンパイル・コマンドで指定した場合も、現行ロケールの LC_UNI_CTYPE カテゴリーによって影響を受ける可能性があります。 この関数は、コンパイル・コマンドに対して LOCALETYPE(*CLD) が指定されている場合には使用できません。詳細については、CCSID およびロケールの理解を参照してください。
ワイド文字関数: 詳細については、ワイド文字 を参照してください。
説明
この関数は、mbtowc() 関数の再始動可能バージョンです。
s が NULL ポインターの場合には、mbrtowc() 関数は初期シフト状態 (エンコードが状態依存でないか、または初期変換状態が記述されている場合はゼロ) を入力するのに必要なバイト数を判別します。 この状態において、pwc パラメーターの値は無視され、結果として、記述されているシフト状態が初期変換状態となります。
s が NULL ポインターではない場合は、mbrtowc() 関数は s によってポイントされているマルチバイト文字 (および先行するシフト・シーケンス) 内のバイト数を判別して対応するマルチバイト文字の値を生成し、 pwc が NULL ポインターではない場合は、その値を pwc によってポイントされているオブジェクト内に保管します。 対応するマルチバイト文字が NULL ワイド文字の場合には、結果の状態は初期変換状態にリセットされます。
この関数は、対応する内部状態のマルチバイト文字関数とは以下の点で異なります。この関数には追加のパラメーターとして mbstate_t の型を指す ps ポインターがあり、このポインターは、関連するマルチバイト文字シーケンスの現在の変換状態を完全に表すことができるオブジェクトを指します。 ps が NULL の場合、この関数は内部の静的変数を状態に使用します。
最大で、n バイトのマルチバイト・ストリングが検証されます。
戻り値
s が NULL ポインターの場合、mbrtowc() 関数は、初期シフト状態を入力するのに必要なバイト数を戻します。 戻り値は MB_CUR_MAX マクロ未満でなければなりません。
変換エラーが発生した場合、errno は ECONVERT に設定される可能性があります。
s が NULL ポインターでない場合、mbrtowc() 関数は、以下のいずれかを戻します。
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
*/
関連情報