wcstombs _wcstombs_l

發行項
02/28/2013

將一連串的寬字元轉換為相對應的一連串的多位元組字元。這些函式更安全版本都可使用; see wcstombs_s _wcstombs_s_l.

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

參數

mbstr
多位元組字元序列的位址。
wcstr
寬字元序列的地址。
count
最大可儲存在多位元組的輸出字串的位元組數。
locale
若要使用地區設定。

傳回值

如果wcstombs成功地將轉換的多位元組的字串，則會傳回多位元組的輸出字串，不包括終止所寫入的位元組數目NULL (如果有的話)。如果mbstr引數是NULL， wcstombs會傳回所需的大小以位元組為單位的目的字串。如果wcstombs遇到廣泛的字元不能轉換為多位元組的字元，則會傳回 – 1 轉換成輸入size_t ，並設定errno到EILSEQ。

備註

wcstombs函式轉換的寬字元字串所指wcstr到對應的多位元組字元，並儲存，會產生mbstr陣列。count參數會指示，可以儲存在多位元組的輸出字串的位元組最大數目 (也就是大小的mbstr)。一般情況下，不知道多少位元組必要時，會轉換為寬字元字串。某些寬的字元必須只有一個位元組在輸出字串。其他人需要兩個。如果輸入字串中每一個寬字元的多位元組的輸出字串中有兩個位元組 (包括寬字元NULL)，以符合執行結果保證。

如果wcstombs之前或當遇到寬字元的 null 字元 ('\ 0' L) count ，就會發生，它將其轉換為 8 位元 0，並停駐點。因此，在多位元組字元字串mbstr是 null 結尾時，才wcstombs在轉換過程中遇到一個寬字元的 null 字元。如果所指的序列wcstr和mbstr重疊，行為的wcstombs尚未定義。

如果mbstr引數是NULL， wcstombs會傳回所需的大小以位元組為單位的目的字串。

wcstombs驗證其參數。如果wcstr是NULL，或是否count大於INT_MAX，如所述，這個函式叫用無效的參數處理常式中，參數驗證。如果執行，則允許繼續執行，此函式會將errno到EINVAL ，並傳回-1。

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

在 C++ 中，這些函式會有範本的多載，叫用這些函式的較新的、安全對應項目。如需詳細資訊，請參閱安全範本多載。

需求

常式	所需的標頭
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

其他的相容性資訊，請參閱相容性在簡介中。

範例

此程式會說明的行為wcstombs函式。

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

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

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

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}