mbsrtowcs

將目前地區設定的多位元組字元字串轉換成對應的寬字元字串，並提供在多位元組字元中間重新啟動的功能。 此函式有更安全的版本可供使用;請參閱 mbsrtowcs_s。

語法

size_t mbsrtowcs(
   wchar_t *wcstr,
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t mbsrtowcs(
   wchar_t (&wcstr)[size],
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

參數

wcstr
用來儲存所產生之已轉換寬字元字串的位址。

mbstr
要轉換之多位元組字元字串位置的間接指標。

count
要轉換並儲存在 wcstr 中的最大字元數 (而不是位元組)。

mbstate
mbstate_t 轉換狀態物件的指標。 如果此值為 null 指標，會使用靜態內部轉換狀態物件。 由於內部 mbstate_t 物件不是安全線程，因此建議您一律傳遞自己的 mbstate 參數。

傳回值

傳回成功轉換的字元數，但不包含結束的 null 字元 (如果有的話)。 如果發生錯誤，則傳回 （size_t）-1，並將 設定 errno 為 EILSEQ。

備註

mbsrtowcs 函式會透過 mbstr 中包含的轉換狀態，將 wcstr 所間接指向的多位元組字元字串，轉換成儲存在緩衝區中由 mbstate 所指向的寬字元。 每個字元的轉換會繼續，直到遇到終止的 Null 多位元組位元、遇到對應到目前地區設定中有效字元的多位元組序列，或直到字元轉換為止 count 。 如果 mbsrtowcs 在發生 count 之前或期間遇到 null 多位元組字元 ('\0')，則會將字元轉換成 16 位元結束的 null 字元並停止。

因此，如果 wcstr 在轉換期間遇到 null 多位元組字元，則 mbsrtowcs 的寬字元字串只能以 null 結束。 如果 mbstr 和 wcstr 所指向的序列重疊，mbsrtowcs 的行為不明。 mbsrtowcs 會受到 LC_TYPE 目前地區設定的類別影響。

函式mbsrtowcs與 _mbstowcs_lmbstowcs 不同之處在於其可重新啟動性。 針對相同或其他可重新啟動的函式的後續呼叫，轉換狀態會儲存在 mbstate 中。 混合使用可重新啟動和不可重新啟動之函式的結果不明。 例如，如果後續使用 對 mbsrtowcs 的呼叫，則應用程式應該使用 mbsrlen 而非mbslen，而不是 mbstowcs。

如果 wcstr 不是 Null 指標，如果轉換因為到達終止的 Null 字元而停止，所指向 mbstr 的指針對象就會被指派為 Null 指標。 否則，它會在最後一個已轉換的多位元組位元元之後指派位址，如果有的話。 它允許後續的函式呼叫重新啟動此呼叫停止的轉換。

wcstr如果自變數是 Null 指標，count則會忽略自變數，並以mbsrtowcs寬字元傳回目的字串所需的大小。 如果 mbstate 是 null 指標，函式會使用非安全執行緒靜態內部 mbstate_t 轉換狀態物件。 如果字元序列 mbstr 沒有對應的多位元組字元表示法，則會傳回 -1，並將 errno 設定為 EILSEQ。

如果 mbstr 為 null 指標，則會叫用無效的參數處理常式，如參數驗證中所述。 若允許繼續執行，此函式會將 errno 設為 EINVAL，並傳回 -1。

在 C++ 中，這個函式具有樣板多載，可以叫用比這個函式更新且更安全的相對版本。 如需詳細資訊，請參閱安全範本多載。

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

例外狀況

mbsrtowcs只要此函式正在執行mbstate，而且自變數不是 Null 指標，函式在目前線程中就不會呼叫setlocale任何函式，函式就會是多線程安全。

需求

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

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit