wcsrtombs_swcsrtombs_s

ワイド文字の文字列をマルチバイト文字の文字列表現に変換します。Convert a wide character string to its multibyte character string representation. これは、「CRT のセキュリティ機能」の説明にあるとおりセキュリティが強化されたバージョンの wcsrtombs です。A version of wcsrtombs with security enhancements as described in Security Features in the CRT.

構文Syntax

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

パラメーターParameters

pReturnValuepReturnValue
Null 終端文字を含む変換された文字列のバイト単位のサイズ。The size in bytes of the converted string, including the null terminator.

mbstrmbstr
結果として変換されたマルチバイト文字の文字列のバッファーのアドレス。The address of a buffer for the resulting converted multibyte character string.

sizeInBytessizeInBytes
バイト単位のサイズ、 mbstrバッファー。The size in bytes of the mbstr buffer.

wcstrwcstr
変換するワイド文字の文字列を指します。Points to the wide character string to be converted.

countcount
格納されるバイトの最大数、 mbstrバッファー、または_TRUNCATEします。The maximum number of bytes to be stored in the mbstr buffer, or _TRUNCATE.

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

戻り値Return Value

正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。Zero if successful, an error code on failure.

エラー条件Error condition 戻り値およびerrnoReturn value and errno
mbstrNULLsizeInBytes > 0mbstr is NULL and sizeInBytes > 0 EINVALEINVAL
wcstrNULLwcstr is NULL EINVALEINVAL
コピー先のバッファーが小さすぎて変換後の文字列を含む (しない限り、カウント_TRUNCATE; 以下の「解説」を参照してください)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; see Remarks below) ERANGEERANGE

これらのいずれかの条件が発生すると、「パラメーターの検証」で説明されているように、無効なパラメーター例外が呼び出されます。If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . 実行の継続が許可された場合、関数はエラー コードを返します設定とerrno表に記載されています。If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

RemarksRemarks

Wcsrtombs_s関数が指すワイド文字の文字列に変換しますwcstrが指すバッファーに格納されるマルチバイト文字にmbstrを使用して、含まれる変換状態呼び出すためします。The wcsrtombs_s function converts a string of wide characters pointed to by wcstr into multibyte characters stored in the buffer pointed to by mbstr, using the conversion state contained in mbstate. これらの条件のいずれかが満たされるまで、各文字に対して変換が続きます。The conversion will continue for each character until one of these conditions is met:

  • ワイド文字の null が検出されました。A null wide character is encountered

  • 変換できないワイド文字が検出されました。A wide character that cannot be converted is encountered

  • 格納されるバイト数、 mbstr equals をバッファーカウントします。The number of bytes stored in the mbstr buffer equals count.

変換後の文字列は、常に null で終わります (エラーの場合も同様)。The destination string is always null-terminated (even in the case of an error).

場合カウント特殊な値は、 _TRUNCATE、しwcsrtombs_sコピー先のバッファーは null の空きを残して収まる限りの文字列の多くに変換されますターミネータ。If count is the special value _TRUNCATE, then wcsrtombs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

場合wcsrtombs_s 、元の文字列を正常に変換に null の終端文字を含む変換された文字列のバイト単位のサイズが置かれる *pReturnValue (提供されているpReturnValueないNULL)。If wcsrtombs_s successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). これが発生した場合でも、 mbstr引数がNULLし、必要なバッファー サイズを決定する方法を提供します。This occurs even if the mbstr argument is NULL and provides a way to determine the required buffer size. その場合mbstrNULLは無視されます。Note that if mbstr is NULL, count is ignored.

場合wcsrtombs_sマルチバイト文字に変換できないワイド文字が検出されたに-1 を入れ *pReturnValue、空の文字列をコピー先のバッファーを設定、設定errnoEILSEQ、し、返しますEILSEQします。If wcsrtombs_s encounters a wide character it cannot convert to a multibyte character, it puts -1 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

によって、シーケンスを指している場合wcstrmbstrの動作が重なるwcsrtombs_sが定義されていません。If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcsrtombs_s is undefined. wcsrtombs_sは現在のロケールの LC_TYPE カテゴリを受けます。wcsrtombs_s is affected by the LC_TYPE category of the current locale.

重要

いることを確認wcstrmbstr重複しないとに変換するワイド文字の数を正確に反映します。Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of wide characters to convert.

Wcsrtombs_s関数とは異なりますwcstombs_s、_wcstombs_s_lによってその再起動します。The wcsrtombs_s function differs from wcstombs_s, _wcstombs_s_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. たとえば、アプリケーションは使用なくwcslen後続の呼び出しの場合は、 wcsrtombs_sの代わりに使用されたwcstombs_s.For example, an application would use wcsrlen rather than wcslen, if a subsequent call to wcsrtombs_s were used instead of wcstombs_s.

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

例外Exceptions

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

Example

// crt_wcsrtombs_s.cpp
//
// 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

void main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

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

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}
The string was successfully converted.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
wcsrtombs_swcsrtombs_s <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