wcrtomb_s

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

語法

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

參數

pReturnValue
傳回寫入的位元組數目，如果發生錯誤則為 -1。

mbchar
產生的多位元組轉換字元。

sizeOfmbchar
mbchar 變數的大小，以位元組為單位。

wchar
要轉換的寬字元。

mbstate
mbstate_t 物件的指標。

傳回值

傳回零，如果發生錯誤則為 errno 值。

備註

wcrtomb_s 函式會轉換寬字元，從 mbstate 包含的指定轉換狀態開始，從 wchar 包含的值中，變成 mbchar 代表的位址。 pReturnValue 值會是轉換的位元組數，但不超過 MB_CUR_MAX 個位元組，如果發生錯誤則為 -1。

如果 mbstate 為 Null，則使用內部的 mbstate_t 轉換狀態。 如果 中包含的 wchar 字元沒有對應的多位元組字元，則 的值 pReturnValue 是 -1，而 函式會傳 errno 回 的值 EILSEQ 。

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

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

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

例外狀況

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

範例

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

需求

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

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
mbsinit