wcrtomb_s

發行項
06/09/2015

轉換寬字元複製到其中的多位元組字元表示。這是 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

參數

[out] pReturnValue
如果發生錯誤則回傳寫入的位元數目或 -1。
[out] mbchar
產生的多個位元組所轉換的字元。
[in] sizeOfmbchar
mbchar 變數的大小 (以位元組為單位)。
[in] wchar
要進行轉換的寬字元。
[in] mbstate
mbstate_t 物件的指標。

傳回值

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

備註

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

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

wcrtomb_s 函式與 wctomb_s、_wctomb_s_l 不同於其重新開始的能力。轉換狀態儲存於 mbstate 讓後續呼叫的相同或其他可重新啟動的函式能夠使用。當混合使用可重新開始和不可重新開始的函式時，結果會是未定義的。例如，如果後續呼叫 wcsrtombs_s 而不是 wcstombs_s.，應用程式可能會使用 wcsrlen ，而不是 wcslen。

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

例外狀況

wcrtomb_s 函式是多執行緒安全，只要在目前執行緒的函式不呼叫 setlocale ，當函式執行時， mbstate 是空的。

範例

// 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");
    }
}