次の方法で共有

wcsrtombs_s

  • [アーティクル]

ワイド文字の文字列をマルチバイト文字の文字列表現に変換します。 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
null 終端文字を含む、変換された文字列のサイズ (バイト単位)。

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 が指すバッファーに格納されるマルチバイト文字に変換します。 これらの条件のいずれかが満たされるまで、各文字に対して変換が続きます。

  • ワイド文字の null が検出されました。

  • 変換できないワイド文字が見つかりました

  • mbstr バッファーに格納されているバイト数が count と同じです。

宛先文字列は常に null で終了します (エラーが発生した場合でも)。

count が特殊値 _TRUNCATE の場合、wcsrtombs_s では null 終端文字用の空きを残して、ターゲット バッファーに収まる限りの文字列を変換します。

ソース文字列 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_lwcstombs_sとは異なります。 同じ関数または再開可能な他の関数の後続の呼び出しのために、変換状態が mbstate に格納されます。 再開可能な関数と再開不可能な関数を混用した場合、結果は未定義です。 たとえば、アプリケーションは wcsrlen を使用し、wcslen は使用しないことがあります。これは、後続の呼び出しで wcsrtombs_s を使用しており、wcstombs_s は使用しない場合です。

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

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

例外

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

int 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.

要件

ルーチンによって返される値 必須ヘッダー
wcsrtombs_s <wchar.h>

関連項目

データ変換
ロケール
マルチバイト文字のシーケンスの解釈
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit