wcstombs_s、_wcstombs_s_l

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

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

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count 
);
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t wcstombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

パラメーター

[出力] pReturnValue
変換された文字数。
[出力] mbstr
変換結果のマルチバイト文字列用のバッファーのアドレス。
[入力] sizeInBytes
mbstr バッファーのサイズ (バイト数)。
[入力] wcstr
変換されるワイド文字列を指します。
[入力] count
mbstr バッファーに格納するワイド文字の最大数 (終端の null 文字は含まない)、または _TRUNCATE。
[入力] locale
使用するロケール。

戻り値

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

エラー条件	戻り値と errno
mbstr が NULL でsizeInBytes > 0	EINVAL
wcstr が NULL です。	EINVAL
変換先バッファーが小さいため変換後の文字列が収まらない (count が _TRUNCATE の場合は例外。下記の「解説」を参照)	ERANGE

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

解説

wcstombs_s 関数は、wcstr が指すワイド文字列を、マルチバイト文字列に変換して mbstr が指すバッファーに格納します。変換は各文字列に対して行われ、次の条件の 1 つが満たされるまで続行されます。

null ワイド文字が検出された
変換できないワイド文字が検出された
mbstr バッファーに格納されたバイト数が count と等しい。

変換後の文字列は、常に null で終わります (エラーの場合も同様)。

count が特殊な値の _TRUNCATE である場合、wcstombs_s は、null 終端文字 1 つ分を残して、変換先バッファーに収まるだけの文字列まで変換を行います。

wcstombs_s は、変換元の文字列の変換に成功すると、null 終端文字を含む変換した文字列のサイズ (バイト単位) を *pReturnValue に設定します (pReturnValue が NULL でない場合)。これは、mbstr 引数が NULL の場合でも発生するので、これを使用して必要なバッファーサイズを確認できます。 mbstr が NULL の場合、count は無視されます。

wcstombs_s は、マルチバイト文字に変換できないワイド文字を検出すると、0 を *pReturnValue に設定し、変換先バッファーに空の文字列を設定します。さらに、errno を EILSEQ に設定し、EILSEQ を返します。

wcstr と mbstr が指す文字列が重なり合う場合、wcstombs_s 関数の動作は未定義です。

セキュリティに関するメモ
wcstr と mbstr が重なり合っていないこと、count が変換対象のワイド文字数を正しく反映していることを確認してください。

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

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

必要条件

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

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

使用例

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

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t   i;
    char      *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE, 
               pWCBuffer, (size_t)BUFFER_SIZE );

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n",
     pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}