mbsrtowcs_s

發行項
02/28/2013

將寬字元字串轉換成它的多位元組字元的字串表示。版本的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

參數

[out] pReturnValue
轉換的字元數。
[out] wcstr
產生的轉換後的寬字元字串的緩衝區的位址。
[out] sizeInWords
大小的wcstr中的字 (也就是寬字元)。
[in] mbstr
指向要轉換的多位元組字元字串的位置。
[in] count
最大的寬字元數目，將儲存wcstr緩衝區，不包括結尾的 null，或_TRUNCATE。
[in] mbstate
變數的指標， mbstate_t轉換狀態物件。

傳回值

零，如果執行成功、失敗的錯誤代碼。

錯誤狀況	傳回值，errno
wcstris NULL and sizeInWords > 0	EINVAL
mbstr 為 NULL	EINVAL
目的緩衝區是太小無法包含轉換後的字串 (除非count是_TRUNCATE。請參閱下方註解)	ERANGE

如果上述條件，就會發生，如所述，會叫用參數不正確的例外狀況參數驗證。如果執行，則允許繼續執行，則函數會傳回一個錯誤碼，並設定errno表格中所示。

備註

mbsrtowcs_s函式將轉換為所指的多位元組字元字串mbstr為儲存在緩衝區所指的寬字元wcstr，使用轉換狀態包含在mbstate。轉換會繼續每個字元，直到滿足這些條件其中一項：

發現多位元組的 null 字元
遇到無效的多位元組字元
儲存在的寬字元數目wcstr緩衝等於count。

目的地字串一定是空字元 (甚至是錯誤)。

如果count是特殊值_TRUNCATE，然後mbsrtowcs_s盡可能將字串轉換容納到目的緩衝區，同時仍留出空間給 null 結束字元。

如果mbsrtowcs_s成功轉換來源的字串，它會將大小放置以寬字元為單位的轉換後的字串，包含 null 結束字元，到*pReturnValue (提供pReturnValue不是NULL)。發生這種情形即使wcstr引數是NULL ，並提供方法，以判斷所需的緩衝區大小。 Note that if wcstr is NULL, count is ignored.

如果mbstate是NULL，內部mbstate_t用轉換狀態。

如果mbsrtowcs_s遇到了無效的多位元組字元，它會為-1 將放置*pReturnValue、設定為空字串的目的緩衝區，會設定errno到EILSEQ，並傳回EILSEQ。

如果所指的序列mbstr和wcstr重疊，行為的mbsrtowcs_s尚未定義。 mbsrtowcs_s會影響目前的地區設定中的 [LC_TYPE] 類別。

安全性提示
確保wcstr和mbstr不會重疊，且該count正確地反映出要轉換的多位元組字元數。

mbsrtowcs_s函式會不同於mbstowcs_s _mbstowcs_s_l由其重新。轉換狀態儲存在mbstate進行後續的呼叫至相同或其他可重新啟動的功能。混合的重新啟動的和即可函式使用時，結果是未定義。例如，應用程式會使用mbsrlen而不是mbslen，如果的後續呼叫mbsrtowcs_s而不是使用mbstowcs_s.

在 C++ 中，以這個函式已經過簡化的樣板的多載。多載可以自動推斷緩衝區長度 (而不必指定 size 引數)，它們可以自動取代較舊的、不安全的函式與其較新的、安全的對應項目。如需詳細資訊，請參閱安全範本多載。