mbstowcs_s、_mbstowcs_s_l

發行項
06/09/2015

轉換寬字元序列至對應的多位元組字元。這些是 mbstowcs、_mbstowcs_l 的安全性增強版本，如 CRT 中的安全性功能中所述。

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count 
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

參數

[out] pReturnValue
要轉換的字元數。
[out] wcstr
緩衝區位址產生的轉換寬字元字串。
[in] sizeInWords
wcstr 緩衝區的大小(以word為單位)。
[in]mbstr
空結尾多位元組字元序列的位址。
[in] count
要儲存的寬字元數目上限在 wcstr 緩衝區，不包括結束的 null 字元或 _TRUNCATE。
[in] locale
要使用的地區設定。

傳回值

若成功則為零，失敗則為錯誤碼。

錯誤狀況	傳回值和 errno
wcstr 為 NULL 而 sizeInWords> 為 0	EINVAL
mbstr 為 NULL	EINVAL
目的端緩衝區太小無法包含已轉換字串(除非 count 是 _TRUNCATE 請參閱 < 備註 >)	ERANGE
wcstr 不是 NULL 且 sizeInWords == 0。	EINVAL

如果其中一個錯誤情況發生，無效的參數叫用例外狀況，如參數驗證中所述。如果執行允許繼續執行，函式會傳回錯誤碼並如表格中所示設定 errno 。

備註

mbstowcs_s 函式轉換被 mbstr 指向的多位元組字元成儲存在緩衝區中被 wcstr 指向的寬字元。每個字元的轉換會繼續，直到下列其中一個條件符合：

遇到多位元組字元 Null
遇到無效的多位元組字元
在 wcstr 緩衝區中的寬字元數目等於 count。

目的資料永遠以 null 結尾 (即使在錯誤的情況下)。

如果 count 是特殊值 _TRUNCATE，則 mbstowcs_s 盡量轉換能放入目的緩衝區的字串，同時保留 null 結束字元的空間。

如果 mbstowcs_s 轉換成功來源字串，它在已轉換字串的寬字元大小，包括 null 結束字元，輸入 *pReturnValue (提供的 pReturnValue 不是 NULL)。即使 wcstr 引數為 NULL 並提供方法來判斷所需的緩衝區大小，也會發生這種情況，。請注意，如果 wcstr 是 NULL， count 會忽略，因此， sizeInWords 必須是 0。

如果 mbstowcs_s 遇到無效的多位元組字元，它將 0 放入 *pReturnValue，將目的緩衝區初始化為空字串，將 errno 設為 EILSEQ，並傳回 EILSEQ。

如果被 mbstr 和 wcstr 指向的序列重疊， mbstowcs_s 行為是未定義。