mbstowcs、_mbstowcs_l

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

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

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

パラメータ

[出力] wcstr
ワイド文字列のアドレス。
[入力] mbstr
null で終わるマルチバイト文字列のアドレス。
[入力] count
変換対象のマルチバイト文字の最大数。
[入力] locale
使用するロケール。

戻り値

元の文字列を正しく変換した場合、mbstowcs 関数は変換されたマルチバイト文字数を返します。wcstr 引数が NULL の場合、この関数は変換先文字列に必要なサイズを (ワイド文字数で) 返します。mbstowcs 関数は、無効なマルチバイト文字を検出した場合は -1 を返します。戻り値が count の場合、ワイド文字列の終端には null 文字が追加されません。

セキュリティに関するメモ :
wcstr と mbstr が重なり合っていないこと、count が変換対象のマルチバイト文字数を正しく反映していることを確認してください。

解説

mbstowcs 関数は、mbstr が指す count 数までのマルチバイト文字を、現在のロケールに基づいて対応するワイド文字列に変換します。結果のワイド文字列は、wcstr の示すアドレスに格納されます。結果は、mbtowc を複数回呼び出した場合と同じです。count 文字数の変換が終わる前または変換が終わったときに 1 バイトの null 文字 (\0) が検出されると、mbstowcs 関数は null 文字をワイド文字の null 文字 (L'\0') に変換して停止します。したがって、wcstr のワイド文字列は、変換時に null 文字が検出された場合にだけ、null で終わる文字列になります。wcstr と mbstr が指す文字列が重なり合う場合、動作は未定義です。

wcstr 引数が NULL の場合、mbstowcs 関数は変換によって得られるワイド文字数を返します。終端の null は含まれません。正しい値が返されるように、ソース文字列は null で終わっている必要があります。結果のワイド文字列に終端の null を含める必要がある場合は、戻り値に 1 を追加します。

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

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

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

必要条件

ルーチン	必須ヘッダー
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

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

使用例

// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function

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

int main( void )
{
    size_t size;
    int nChar = 2; // number of characters to convert
    int requiredSize;

    unsigned char    *pmbnull  = NULL;
    unsigned char    *pmbhello = NULL;
    char* localeInfo;
    
    wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
    wchar_t *pwc;

    /* Enable the Japanese locale and codepage */
    localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
    printf("Locale information set to %s\n", localeInfo);
    
    printf( "Convert to multibyte string:\n" );

    requiredSize = wcstombs( NULL, pwchello, 0); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    printf("  Required Size: %d\n", requiredSize);

    /* Add one to leave room for the null terminator. */
    pmbhello = (unsigned char *)malloc( requiredSize + 1);
    if (! pmbhello)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    if (size == (size_t) (-1))
    {
        printf("Couldn't convert string. Code page 932 may"
                " not be available.\n");
        return 1;
    }
    printf( "  Number of bytes written to multibyte string: %u\n",
            (unsigned int) size );
    printf( "  Hex values of the " );
    printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
            pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
    printf( "  Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");

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

    /* Assume we don't know the length of the multibyte string.
     Get the required size in characters, and allocate enough space. */

    requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
    /* Add one to leave room for the NULL terminator */
    pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
    if (! pwc)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
    if (size == (size_t) (-1))
    {
       printf("Couldn't convert string--invalid multibyte character.\n");
    }
    printf( "  Characters converted: %u\n", (unsigned int)size );
    printf( "  Hex value of first 2" );
    printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
    free(pwc);
    free(pmbhello);
}

Locale information set to Japanese_Japan.932
Convert to multibyte string:
  Required Size: 4
  Number of bytes written to multibyte string: 4
  Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1
  Codepage 932 uses 0x81 to 0x9f as lead bytes.

Convert back to wide-character string:
  Characters converted: 2
  Hex value of first 2 wide characters: 0x3042 0x3043