共用方式為

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