wcstombs、_wcstombs_l

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

ワイド文字列を対応するマルチバイト文字列に変換します。これらの関数のセキュリティを強化したバージョンについては、「wcstombs_s、_wcstombs_s_l」を参照してください。

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

パラメーター

mbstr
マルチバイト文字列のアドレス。
wcstr
ワイド文字列のアドレス。
count
マルチバイト出力文字列に格納できる最大バイト数。
locale
使用するロケール。

戻り値

マルチバイト文字列への変換が正常に終了した場合、wcstombs 関数はマルチバイト出力文字列に書き込まれるバイト数を返します。ただし、終端の NULL (ある場合) は除外します。 mbstr 引数が NULL の場合、wcstombs は変換先文字列に必要なサイズをバイト数で返します。 wcstombs 関数は、マルチバイト文字に変換できないワイド文字を検出すると、size_t 型にキャストした –1 を返し、errno を EILSEQ に設定します。

解説

wcstombs 関数は、wcstr が指すワイド文字列を対応するマルチバイト文字列に変換し、結果を mbstr 配列に格納します。パラメーター count には、マルチバイト出力文字列に格納できる最大バイト数 (mbstr のサイズ) を指定します。通常、ワイド文字列を変換するときに必要なバイト数は不明です。出力文字列に 1 バイトしか必要としないワイド文字と、2 バイト必要なワイド文字があります。入力文字列にあるすべてのワイド文字 (ワイド文字の NULL も含む) に対して、マルチバイト出力文字列内で 2 バイトがある場合、結果は確実に出力文字列に収まります。

count に指定した値以内で wcstombs 関数がワイド文字の null 文字 (L'\0') を検出すると、8 ビットの 0 に変換して停止します。したがって、mbstr のマルチバイト文字の文字列が null で終わるのは、wcstombs 関数が変換時にワイド文字の null 文字を検出した場合だけです。 wcstr と mbstr が指す文字列が重なり合う場合、wcstombs 関数の動作は未定義です。

mbstr 引数が NULL の場合、wcstombs は変換先文字列に必要なサイズをバイト数で返します。

wcstombs は、パラメーターを検証します。 wcstr が NULL の場合、または count がINT_MAX を超える場合、この関数は「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーを呼び出します。実行の継続が許可された場合、この関数は errno を EINVAL に設定し、-1 を返します。

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

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

必要条件

ルーチン	必須ヘッダー
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

次のプログラムは、wcstombs 関数の動作を示しています。

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}