wcsrtombs_s

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

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

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

パラメータ

[出力] pReturnValue
変換された文字数。
[出力] mbstr
変換結果のマルチバイト文字列用のバッファのアドレス。
[出力] sizeInBytes
mbstr バッファのサイズ (バイト数)。
[入力] wcstr
変換されるワイド文字列を指します。
[入力] count
mbstr バッファに格納される最大バイト数または _TRUNCATE。
[入力] mbstate
mbstate_t 変換状態オブジェクトへのポインタ。

戻り値

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

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

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

解説

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

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

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

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

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

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

wcstr と mbstr が指すシーケンスが重複する場合、wcsrtombs_s の動作は未定義です。wcsrtombs_s は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

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

wcsrtombs_s 関数は、再起動できるかどうかに関して、wcstombs_s、_wcstombs_s_l と異なります。変換状態は、同じまたは他の再起動可能な関数を後で呼び出すために mbstate に格納されます。再起動可能な関数と再起動不可能な関数を混在させた場合は、予測できない結果になる可能性があります。たとえば、後で wcstombs_s. ではなく wcsrtombs_s を呼び出す場合、アプリケーションは wcslen ではなく wcsrlen を使用します。

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

例外

wcsrtombs_s 関数は、この関数の実行中に現在のスレッドで setlocale を呼び出す関数がなく、mbstate が null である限り、マルチスレッドセーフです。

使用例

// crt_wcsrtombs_s.cpp
// 
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

void main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.