共用方式為


wcsrtombs_s

將寬字元字串轉換為其多位元組字元字串表示法。 版本wcsrtombs具有CRT中的安全性功能中所述的安全性增強功能。

語法

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

參數

pReturnValue
已轉換字串的位元組大小,包括 Null 終止符。

mbstr
所產生之已轉換的多位元組字串的緩衝區位址。

sizeInBytes
mbstr 緩衝區的大小,以位元組為單位。

wcstr
指向要轉換的寬字元字串。

count
要儲存在緩衝區中的 mbstr 位元組數目上限,或 _TRUNCATE

mbstate
mbstate_t 轉換狀態物件的指標。

傳回值

如果成功,則為零,如果失敗,則為錯誤碼。

錯誤狀況 傳回值和 errno
mbstrNULLsizeInBytes> 0 EINVAL
wcstrNULL EINVAL
目的緩衝區太小,無法包含已轉換的字串 (除非 count_TRUNCATE,請參閱下面的<備註>) ERANGE

如果發生上述任一情況,則會叫用無效的參數例外狀況,如參數驗證中所述。 如果允許繼續執行,此函式會傳回錯誤碼,並將 errno 設為如表中所示。

備註

wcsrtombs_s 函式會將 wcstr 指向的寬字元字串轉換成儲存在 mbstr 所指向緩衝區的多位元組字元,使用 mbstate 包含的轉換狀態。 除非遇到下列情況之一,否則會繼續為每個字元進行轉換:

  • 遇到 Null 寬字元

  • 遇到無法轉換的寬字元

  • mbstr 緩衝區中儲存的位元組數目等於 count

目的地字串一律為 Null 終止(即使發生錯誤也一樣)。

如果 count 是特殊值 _TRUNCATE,則會 wcsrtombs_s 將和 符合目的緩衝區一樣多的字串轉換成 ,同時仍保留 Null 終止符的空間。

如果 wcsrtombs_s 成功轉換來源字串,則會將已轉換字串的大小以位元組為單位,包括 Null 終止符,放入 *pReturnValue (未提供 pReturnValue NULL)。 即使自變數為 NULL,也會計算mbstr大小;它提供方法來判斷所需的緩衝區大小。 如果 mbstrNULLcount 則會忽略 。

如果 wcsrtombs_s 遇到無法轉換成多位元組字元的寬字元,則會將 *pReturnValue-1 放入 ,將目的地緩衝區設定為空字串、設定 errnoEILSEQ,並傳 EILSEQ回 。

如果 wcstrmbstr 所指向的序列重疊,wcsrtombs_s 的行為不明。 wcsrtombs_s 受到目前地區設定之 LC_TYPE 分類的影響。

重要

確定 wcstrmbstr 不會重疊,而且 count 正確反映要轉換的寬字元數。

函式wcsrtombs_s_wcstombs_s_lwcstombs_s 不同之處在於其可重新啟動性。 針對相同或其他可重新啟動的函式的後續呼叫,轉換狀態會儲存在 mbstate 中。 混合使用可重新啟動和不可重新啟動之函式的結果不明。 例如,如果使用了 wcsrtombs_s 的後續呼叫,而不是 wcstombs_s,應用程式應該使用 wcsrlen,而不是 wcslen

C++ 利用多載樣板簡化了這些函式的使用方式。多載可自動推斷緩衝區長度 (因而不須指定大小引數),也可以將不安全的舊函式自動取代成較新且安全的對應函式。 如需詳細資訊,請參閱安全範本多載

根據預設,此函式的全域狀態會限定於應用程式。 若要變更此行為,請參閱 CRT 中的全域狀態

例外狀況

wcsrtombs_s 函式是安全多執行緒,但前提是當這個函式執行中、且 mbstate 為 Null 時,目前執行緒中沒有任何函式呼叫 setlocale

範例

// 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

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;
    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.

需求

常式 必要的標頭
wcsrtombs_s <wchar.h>

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit