wcrtomb_s

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

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

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

パラメーター

[出力] pReturnValue
書き込まれたバイト数。エラーが発生した場合は -1。
[出力] mbchar
結果としてマルチバイトに変換された文字。
[入力] sizeOfmbchar
mbchar 変数のサイズ (バイト単位)。
[入力] wchar
変換するワイド文字。
[入力] mbstate
mbstate_t オブジェクトへのポインター。

戻り値

0 を返します。エラーが発生した場合は errno の値を返します。

解説

wcrtomb_s 関数は、wchar に格納されている値のワイド文字を変換し mbchar で表すアドレスに格納します。このとき、変換は mbstate に含まれる指定された変換状態から始められます。 pReturnValue の値は、MB_CUR_MAX バイト数以下の変換されたバイト数になります。エラーが発生した場合は -1 になります。

mbstate が null の場合は、内部 mbstate_t 変換状態が使用されます。 wchar に含まれる文字に対応するマルチバイト文字がない場合、pReturnValue の値は -1 となり、この関数は errno の値として EILSEQ を返します。

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

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

例外

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

使用例

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}