wcstombs_s、_wcstombs_s_l

發行項
06/09/2015

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

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

參數

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

傳回值

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

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

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

備註

wcstombs_s 函式轉換寬字元字串指向 wcstr 輸入緩衝區中的多位元組字元所指向的 mbstr。每個字元的轉換會繼續，直到下列其中一個條件符合：

遇到空寬字元
遇到無法轉換的寬字元
在 mbstr 緩衝區中位元組數目等於 count。

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

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

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

如果wcstombs_s 遇到無法轉換到多位元組字元的寬字元，它在 *pReturnValue放 0，將目的緩衝區初始化為空字串，將 errno 設為 EILSEQ，並傳回 EILSEQ。

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

安全性提示
確認 wcstr 和 mbstr 不重疊，而 count ，正確反映轉換寬字元的數目。

wcstombs_s 在區域設定相依的動作時使用目前的區域設定，_wcstombs_s_l 除了使用傳入的區域設定以外與wcstombs 是相同的。如需詳細資訊，請參閱地區設定。

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

需求

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

如需其他相容性資訊，請參閱＜簡介＞中的相容性。

範例

這個程式說明 wcstombs_s 函式的行為。

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t   i;
    char      *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE, 
               pWCBuffer, (size_t)BUFFER_SIZE );

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n",
     pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}