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