wcstombs_s, _wcstombs_s_l

  • [アーティクル]

ワイド文字のシーケンスを、対応するマルチバイト文字のシーケンスに変換します。 CRT の_wcstombs_lwcstombsセキュリティ機能に関する説明に従って、セキュリティが強化されたバージョン。

構文

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
null 終端文字を含む、変換された文字列のサイズ (バイト単位)。

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

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

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

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

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

count が特殊値 _TRUNCATE の場合、wcstombs_s では null 終端文字用の空きを残して、ターゲット バッファーに収まる限りの文字列を変換します。 文字列が切り詰められる場合、戻り値は STRUNCATE であり、変換は成功と見なされます。

wcstombs_sソース文字列が正常に変換されると、変換された文字列のサイズ (null ターミネータを含む) が (指定pReturnValueされていないNULL場合) に*pReturnValue格納されます。 引数が ;の場合 mbstr でも、サイズが NULL計算され、必要なバッファー サイズを決定する方法が提供されます。 mbstr が NULL の場合、count は無視されます。

マルチバイト文字に変換できないワイド文字が検出された場合wcstombs_sは、0 *ReturnValueを入力し、宛先バッファーを空の文字列に設定し、にEILSEQ設定errnoして、返しますEILSEQ。

wcstr および mbstr が指すシーケンスが重なり合う場合、wcstombs_s の動作は未定義です。

重要

wcstr と mbstr が重なり合わず、変換するワイド文字の数が count に適切に反映されていることを確認します。

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

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

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

必要条件

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

互換性の詳細については、「 Compatibility」を参照してください。

例

このプログラムは、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 );
    const 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 - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

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

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

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

関連項目

データ変換
ロケール
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte