wcstombs、_wcstombs_lwcstombs, _wcstombs_l

ワイド文字のシーケンスを、対応するマルチバイト文字のシーケンスに変換します。Converts a sequence of wide characters to a corresponding sequence of multibyte characters. これらの関数のセキュリティを強化したバージョンを使用できます。「wcstombs_s、_wcstombs_s_l」をご覧ください。More secure versions of these functions are available; see wcstombs_s, _wcstombs_s_l.

構文Syntax

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

パラメーターParameters

mbstrmbstr
マルチバイト文字のシーケンスのアドレス。The address of a sequence of multibyte characters.

wcstrwcstr
ワイド文字のシーケンスのアドレス。The address of a sequence of wide characters.

countcount
マルチバイト出力文字列に格納できる最大バイト数。The maximum number of bytes that can be stored in the multibyte output string.

localelocale
使用するロケール。The locale to use.

戻り値Return Value

場合wcstombsマルチバイト文字列を正常に変換 (ある場合)、終端の null を除く、マルチバイト出力文字列に書き込まれたバイト数を返します。If wcstombs successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating null (if any). 場合、 mbstr引数がNULLwcstombs対象文字列のバイト単位で必要なサイズを返します。If the mbstr argument is NULL, wcstombs returns the required size in bytes of the destination string. 場合wcstombsマルチバイト文字に変換できないワイド文字が検出された型にキャストする-1 を返しますsize_t設定とerrnoEILSEQ.If wcstombs encounters a wide character it cannot convert to a multibyte character, it returns -1 cast to type size_t and sets errno to EILSEQ.

RemarksRemarks

Wcstombs関数が指すワイド文字の文字列に変換wcstrに対応するマルチバイト文字の文字し、に結果を格納、 mbstr配列。The wcstombs function converts the wide-character string pointed to by wcstr to the corresponding multibyte characters and stores the results in the mbstr array. カウントパラメーターはマルチバイト出力文字列に格納できるバイトの最大数を示します (のサイズは、 mbstr)。The count parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of mbstr). 通常、ワイド文字列を変換するときに必要になるバイト数は不明です。In general, it is not known how many bytes will be required when converting a wide-character string. 出力文字列の 1 バイトだけを必要とするワイド文字もあれば、2 バイトを必要とする文字もあります。Some wide characters will require only one byte in the output string; others require two. (ワイド文字の null を含む) 入力文字列内のすべてのワイド文字をマルチバイト出力文字列に 2 バイトがある場合は、結果を必ず収まります。If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character null), the result is guaranteed to fit.

場合wcstombs前に、かワイド文字の null 文字 (L '\0') が発生したカウント発生するに変換する 8 ビット 0 して停止します。If wcstombs encounters the wide-character null character (L'\0') either before or when count occurs, it converts it to an 8-bit 0 and stops. したがって、マルチバイト文字の文字列mbstrが null で終わる場合にのみwcstombs変換中にワイド文字の null 文字を検出するとします。Thus, the multibyte character string at mbstr is null-terminated only if wcstombs encounters a wide-character null character during conversion. によって、シーケンスを指している場合wcstrmbstrの動作が重なるwcstombsが定義されていません。If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs is undefined.

場合、 mbstr引数がNULLwcstombs対象文字列のバイト単位で必要なサイズを返します。If the mbstr argument is NULL, wcstombs returns the required size in bytes of the destination string.

wcstombsパラメーターを検証します。wcstombs validates its parameters. 場合wcstrNULL、またはカウントがより大きいINT_MAX、」の説明に従って、この関数は、無効なパラメーター ハンドラーを呼び出しますパラメーターの検証です。If wcstr is NULL, or if count is greater than INT_MAX, this function invokes the invalid parameter handler, as described in Parameter Validation . 実行の継続が許可された場合、関数は設定errnoEINVAL -1 を返します。If execution is allowed to continue, the function sets errno to EINVAL and returns -1.

wcstombsロケールに依存する動作に現在のロケールを使用 _wcstombs_l代わりに渡されたロケールを使用すると同じです。wcstombs uses the current locale for any locale-dependent behavior; _wcstombs_l is identical except that it uses the locale passed in instead. 詳細については、「 Locale」を参照してください。For more information, see Locale.

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
wcstombswcstombs <stdlib.h><stdlib.h>
_wcstombs_l_wcstombs_l <stdlib.h><stdlib.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

このプログラムの動作を示しています、 wcstombs関数。This program illustrates the behavior of the wcstombs function.

// 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);
}
Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

関連項目See also

データ変換Data Conversion
ロケールLocale
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l
mbstowcs、_mbstowcs_lmbstowcs, _mbstowcs_l
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
wctomb、_wctomb_lwctomb, _wctomb_l
WideCharToMultiByteWideCharToMultiByte