Share via

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
mbstr是 NULL 和 sizeInBytes> 0 EINVAL
wcstr 是 NULL EINVAL
目的緩衝區太小，無法包含已轉換的字串 (除非 count 是 _TRUNCATE，請參閱下面的＜備註＞) ERANGE

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

備註

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

  • 遇到 Null 寬字元

  • 遇到無法轉換的寬字元

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

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

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

如果 wcsrtombs_s 成功轉換來源字串，則會將已轉換字串的大小以位元組為單位，包括 Null 結束字元，放入 *pReturnValue （未提供 pReturnValueNULL ）。 即使引數為 NULL ，也會計算 mbstr 大小;它提供方法來判斷所需的緩衝區大小。 如果 mbstr 為 NULL ， count 則會忽略 。

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

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

重要

確定 wcstr 和 mbstr 不會重疊，而且 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