wcstombs_s _wcstombs_s_l

發行項
02/28/2013

將一連串的寬字元轉換為相對應的一連串的多位元組字元。版本的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
mbstris NULL and sizeInBytes > 0	EINVAL
wcstr 為 NULL	EINVAL
目的緩衝區是太小無法包含轉換後的字串 (除非count是_TRUNCATE。請參閱下方註解)	ERANGE

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

備註

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

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

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

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

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

如果wcstombs_s遇到廣泛的字元不能轉換為多位元組的字元，它會將 0 放*pReturnValue，將目的緩衝區設定為空字串，設定errno到EILSEQ，並傳回EILSEQ。

如果所指的序列wcstr和mbstr重疊，行為的wcstombs_s尚未定義。

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

wcstombs_s使用目前的地區設定的任何地區設定相關的行為。 _wcstombs_s_l是相同的wcstombs不同之處在於它所使用的地區設定中傳遞。如需詳細資訊，請參閱地區設定。

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

需求

常式	所需的標頭
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);
    }
}