wctomb_s、_wctomb_s_l

[アーティクル]
08/09/2011

ワイド文字を対応するマルチバイト文字に変換します。この関数は、「CRT のセキュリティ機能」に説明されているように、wctomb、_wctomb_l のセキュリティが強化されたバージョンです。

errno_t wctomb_s(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar 
);
errno_t _wctomb_s_l(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar,
   _locale_t locale
);

パラメーター

[出力] pRetValue
バイト数、または結果を示すコード。
[出力] mbchar
マルチバイト文字のアドレス。
[入力] sizeInBytes
mbchar バッファーのサイズ。
[入力] wchar
ワイド文字。
[入力] locale
使用するロケール。

戻り値

正常終了した場合は 0 を返します。失敗した場合はエラーコードを返します。

エラー条件

mbchar	sizeInBytes	戻り値	pRetValue
NULL	0 より大きい	EINVAL	変更されない
any	>INT_MAX	EINVAL	変更されない
any	小さすぎる	EINVAL	変更されない

上記のいずれかのエラー条件が発生すると、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、wctomb は EINVAL を返し、errno を EINVAL に設定します。

解説

wctomb_s 関数は、引数 wchar を対応するマルチバイト文字に変換し、結果を mbchar に格納します。この関数はプログラムのどこからでも呼び出せます。

wctomb_s 関数でワイド文字をマルチバイト文字に変換する場合、この関数はそのワイド文字のバイト数 (必ず MB_CUR_MAX 以下) を pRetValue が指す整数で示します。 wchar がワイド文字の null 文字 (L'\0') の場合、wctomb_s 関数は pRetValue に 1 を格納します。変換先のポインター mbchar が NULL の場合、wctomb_s 関数は pRetValue に 0 を格納します。現在のロケールでは変換ができない場合、wctomb_s 関数は pRetValue に -1 を格納します。

wctomb_s は、ロケールに依存する情報に現在のロケールを使用します。_wctomb_s_l は、渡されたロケールを代わりに使用することを除いて同じです。詳細については、「ロケール」を参照してください。

必要条件

ルーチン	必須ヘッダー
wctomb_s	<stdlib.h>
_wctomb_s_l	<stdlib.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

次のプログラムは、wctomb 関数の動作を示しています。

// crt_wctomb_s.cpp
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    int i;
    wchar_t wc = L'a';
    char *pmb = (char *)malloc( MB_CUR_MAX );

    printf_s( "Convert a wide character:\n" );
    wctomb_s( &i, pmb, MB_CUR_MAX, wc );
    printf_s( "   Characters converted: %u\n", i );
    printf_s( "   Multibyte character: %.1s\n\n", pmb );
}