wcrtomb_s

發行項
02/28/2013

寬字元轉換為它的多位元組字元表示。版本的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 和函式會傳回errno的值EILSEQ。

wcrtomb_s函式會不同於wctomb_s _wctomb_s_l由其重新。轉換狀態儲存在mbstate進行後續的呼叫至相同或其他可重新啟動的功能。混合的重新啟動的和即可函式使用時，結果是未定義。例如，應用程式會使用wcsrlen而不是wcslen，如果的後續呼叫wcsrtombs_s而不是使用wcstombs_s.

在 C++ 中，以這個函式已經過簡化的樣板的多載。多載可以自動推斷緩衝區長度 (而不必指定 size 引數)，它們可以自動取代較舊的、不安全的函式與其較新的、安全的對應項目。如需詳細資訊，請參閱安全範本多載。

例外狀況

wcrtomb_s函式為多執行緒的安全，只要在目前的執行緒中的函式會呼叫setlocale這個函式執行時， mbstate為 null。

範例

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