mbsrtowcs_s

將目前的地區設定的多位元組字元字串，轉換為寬字元字串的表示。 版本 mbsrtowcs 具有 CRT 中的安全性功能中所述 的安全性增強功能。

語法

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

參數

pReturnValue
已轉換的字元數。

wcstr
緩衝區位址，要儲存產生的已轉換寬字元字串。

sizeInWords
wcstr 的大小 (字數) (寬字元)。

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

count
要儲存在緩衝區中的 wcstr 寬字元數目上限，不包括終止 Null 或 _TRUNCATE 。

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

傳回值

如果轉換成功為零，若失敗則為錯誤碼。

錯誤狀況	傳回值和 errno
wcstr是 null 指標，而 sizeInWords> 0	EINVAL
mbstr 為 null 指標	EINVAL
間接指向 的 mbstr 字串包含對目前地區設定不正確多位元組序列。	EILSEQ
目的緩衝區太小，無法包含已轉換的字串 (除非 count 是 _TRUNCATE；如需詳細資訊，請參閱＜備註＞)	ERANGE

如果發生上述任一情況，則會叫用不正確參數例外狀況，如參數驗證 中所述 。 如果允許繼續執行，此函式會傳回錯誤碼，並將 errno 設為如表中所示。

備註

mbsrtowcs_s 函式會使用 mbstr 中所包含的轉換狀態，將 wcstr 間接所指向的多位元組字元字串，轉換為儲存在緩衝區中 mbstate 所指向的寬字元。 除非遇到下列情況之一，否則會繼續為每個字元進行轉換：

• 遇到多位元組的 null 字元

• 遇到無效的多位元組字元

• 儲存在 wcstr 緩衝區的寬字元數目等於 count。

除非是 Null 指標，否則目的地字串 wcstr 一律會以 Null 終止，即使 wcstr 發生錯誤也一樣。

如果 count 是特殊值 _TRUNCATE ， mbsrtowcs_s 則會將和 符合目的緩衝區一樣多的字串轉換，同時仍保留 Null 結束字元的空間。

如果 mbsrtowcs_s 成功轉換來源字串，它會將已轉換字串的大小放入寬字元，並將 Null 結束字元放入 *pReturnValue ，但前提是 pReturnValue 不是 Null 指標。 即使 wcstr 引數是 Null 指標，也會計算大小，這可讓您判斷所需的緩衝區大小。 如果 wcstr 為 Null 指標， count 則會忽略 。

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

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

如果 mbsrtowcs_s 遇到目前地區設定中不正確多位元組字元，則會將 -1 *pReturnValue 放入 ，將目的地緩衝區 wcstr 設定為空字串、設定 errno 為 EILSEQ ，並傳 EILSEQ 回 。

如果 mbstr 和 wcstr 所指向的序列重疊，mbsrtowcs_s 的行為不明。 mbsrtowcs_s 會受到 LC_TYPE 目前地區設定的類別影響。

重要

確定 wcstr 和 mbstr 沒有重疊，而且 count 正確反映要轉換的多位元組字元數。

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

在 C++ 中，範本多載會簡化使用此函式;多載可以自動推斷緩衝區長度（不需要指定 size 引數），而且可以使用較新的安全對應專案自動取代較舊的非安全函式。 如需詳細資訊，請參閱 保護範本多載 。

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

例外狀況

mbsrtowcs_s只要此函式正在執行，而且 mbstate 引數不是 Null 指標，則函式在目前線程中沒有任何函式呼叫 setlocale ，則函式是多執行緒安全。

需求

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

另請參閱

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