wcsrtombswcsrtombs

ワイド文字の文字列をマルチバイト文字の文字列形式に変換します。Convert a wide character string to its multibyte character string representation. この関数のセキュリティが強化されたバージョンについては、「wcsrtombs_s」を参照してください。A more secure version of this function is available; see wcsrtombs_s.

構文Syntax

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

パラメーターParameters

mbstrmbstr
結果として変換されたマルチバイト文字のアドレスの場所。The resulting converted multibyte character string's address location.

wcstrwcstr
変換されるワイド文字の文字列の場所を間接的に指します。Indirectly points to the location of the wide character string to be converted.

countcount
変換される文字数。The number of character to be converted.

mbstatembstate
Mbstate_tの変換状態オブジェクトへのポインター。A pointer to an mbstate_t conversion state object.

戻り値Return Value

正常に変換されたバイト数を返します (null で終了する null バイトがあっても含まれません)。それ以外の場合は、エラーが発生した場合に -1 を返します。Returns the number of bytes successfully converted, not including the null terminating null byte (if any), otherwise a -1 if an error occurred.

RemarksRemarks

Wcsrtombs関数は、 mbstateに含まれる指定された変換の状態で始まるワイド文字の文字列を、 wcstrの間接的な値からmbstrのアドレスに変換します。The wcsrtombs function converts a string of wide characters, beginning in the specified conversion state contained in mbstate, from the values indirect pointed to in wcstr, into the address of mbstr. 変換は、null 終端ワイド文字が検出された後、対応していない文字が検出されたとき、または次の文字がカウントに含まれる制限を超えたときまで、各文字に対して続行されます。The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in count. Wcsrtombsが、 countの前または後に、ワイド文字の null 文字 (L ' \ 0 ') を検出すると、それを8ビットの0に変換して停止します。If wcsrtombs 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のマルチバイト文字列は、 wcsrtombsが変換中にワイド文字の null 文字を検出した場合にのみ、null で終了します。Thus, the multibyte character string at mbstr is null-terminated only if wcsrtombs encounters a wide character null character during conversion. Wcstrmbstrが指すシーケンスが重なり合う場合、 wcsrtombsの動作は未定義になります。If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcsrtombs is undefined. wcsrtombsは、現在のロケールの LC_TYPE カテゴリの影響を受けます。wcsrtombs is affected by the LC_TYPE category of the current locale.

Wcsrtombs関数は、 wcstombs、_wcstombs_lの再起動によって異なります。The wcsrtombs function differs from wcstombs, _wcstombs_l by its restartability. 変換状態は、同じまたはその他の再開可能な関数への後続の呼び出しのためにmbstateに格納されます。The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. 再開可能な関数と再開不可能な関数を混用した場合、結果は未定義です。Results are undefined when mixing the use of restartable and nonrestartable functions. たとえば、 wcstombsの代わりにwcsrtombsの後続の呼び出しが使用された場合、アプリケーションはwcsrlenではなくwcsrlenを使用します。For example, an application would use wcsrlen rather than wcsnlen, if a subsequent call to wcsrtombs were used instead of wcstombs.

Mbstr引数がNULLの場合、 wcsrtombsは、コピー先の文字列の必要なサイズをバイト単位で返します。If the mbstr argument is NULL, wcsrtombs returns the required size in bytes of the destination string. Mbstateが null の場合、内部mbstate_tの変換状態が使用されます。If mbstate is null, the internal mbstate_t conversion state is used. 文字シーケンスwcharに対応するマルチバイト文字表現がない場合は、-1 が返され、 errnoEILSEQに設定されます。If the character sequence wchar does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

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

例外Exceptions

Wcsrtombs関数は、この関数の実行中に現在のスレッドの関数がsetlocaleを呼び出しておらず、 mbstateが null でない限り、マルチスレッドセーフです。The wcsrtombs function is multithread safe as long as no function in the current thread calls setlocale while this function is executing and the mbstate is not null.

Example

// crt_wcsrtombs.cpp
// compile with: /W3
// 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;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}
The string was successfuly converted.

必要条件Requirements

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

関連項目See also

データ変換Data Conversion
ロケールLocale
マルチバイト文字のシーケンスの解釈Interpretation of Multibyte-Character Sequences
wcrtombwcrtomb
wcrtomb_swcrtomb_s
wctomb、_wctomb_lwctomb, _wctomb_l
wcstombs、_wcstombs_lwcstombs, _wcstombs_l
mbsinitmbsinit