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 （未提供 pReturnValue NULL）。 即使自變數為 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