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関数に含まれる指定された変換の状態で始まるワイド文字の文字列を変換する呼び出すためで指す間接の値から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前に、かワイド文字の 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が null で終わる場合にのみwcsrtombs変換中にワイド文字の 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. 変換の状態が格納されている呼び出すため同じか、またはその他の再開可能な関数を呼び出すのためです。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. たとえば、アプリケーションは使用なくwcsnlen後続の呼び出しの場合は、 wcsrtombsの代わりに使用されたwcstombs.For example, an application would use wcsrlen rather than wcsnlen, if a subsequent call to wcsrtombs were used instead of wcstombs.

場合、 mbstr引数がNULLwcsrtombs対象文字列のバイト単位で必要なサイズを返します。If the mbstr argument is NULL, wcsrtombs returns the required size in bytes of the destination string. 場合呼び出すためが null の場合、内部mbstate_t変換状態を使用します。If mbstate is null, the internal mbstate_t conversion state is used. 場合の文字シーケンスwcharが対応するマルチバイト文字の表現、-1 が返されます、 errnoに設定されているEILSEQします。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この関数の実行中に、呼び出すためが 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