mbstowcs_s, _mbstowcs_s_l

將多位元組字元序列轉換成對應的寬字元序列。 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

參數

pReturnValue
已轉換的字元數。

wcstr
所產生之已轉換寬字元字串的緩衝區位址。

sizeInWords
wcstr 緩衝區的大小 (以字組為單位)。

mbstr
以 Null 結束之多位元組字元序列的位址。

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

locale
要使用的地區設定。

傳回值

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

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

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

備註

mbstowcs_s 函式會將 wcstr 所指向的多位元組字元字串，轉換成儲存在緩衝區中由 mbstr 所指向的寬字元。 除非遇到下列情況之一，否則會繼續為每個字元進行轉換：

• 遇到多位元組的 null 字元

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

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

目的地字串一律為 Null 終止（即使發生錯誤也一樣）。

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

如果 mbstowcs_s 成功轉換來源字串，它會將已轉換字串的大小放入包含 Null 結束字元的寬字元中 *pReturnValue （未提供 pReturnValueNULL ）。 即使 wcstr 引數為 NULL ，也會計算大小，並提供方法來判斷所需的緩衝區大小。 如果 wcstr 為 NULL ， count 則會忽略 ，而且 sizeInWords 必須是 0。

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

如果 mbstr 和 wcstr 所指向的序列重疊，mbstowcs_s 的行為不明。

重要

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

mbstowcs_s 會針對任何與地區設定相關的行為使用目前的地區設定；_mbstowcs_s_l 與其相同，只不過它會改用傳入的地區設定。 如需詳細資訊，請參閱 Locale。

C++ 利用多載樣板簡化了這些函式的使用方式。多載可自動推斷緩衝區長度 (因而不須指定大小引數)，也可以將不安全的舊函式自動取代成較新且安全的對應函式。 如需詳細資訊，請參閱 保護範本多載 。

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

需求

常式	必要的標頭
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

如需相容性詳細資訊，請參閱相容性。

另請參閱

資料轉換
地區設定
MultiByteToWideChar
多位元組字元序列的解譯
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l