wcrtomb_s

ワイド文字をマルチバイト文字の表現に変換します。 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 関数は、mbstate に含まれる指定された変換の状態で始まるワイド文字を、wchar に含まれている値から、mbchar によって表されるアドレスに変換します。 pReturnValue 値は変換されたバイト数になりますが、MB_CUR_MAX バイトより多くはなりません。エラーが発生した場合は、-1 が返されます。

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

wcrtomb_s関数は、再起動可能性によって_wctomb_s_lwctomb_sとは異なります。 同じ関数または再開可能な他の関数の後続の呼び出しのために、変換状態が mbstate に格納されます。 再開可能な関数と再開不可能な関数を混用した場合、結果は未定義です。 たとえば、アプリケーションは wcsrlen を使用し、wcslen は使用しないことがあります。これは、後続の呼び出しで wcsrtombs_s を使用しており、wcstombs_s は使用しない場合です。

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

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

例外

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");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

要件

関連項目

データ変換
ロケール
マルチバイト文字のシーケンスの解釈
mbsinit