共用方式為


wcstombs_s, _wcstombs_s_l

將一連串的寬字元轉換為對應的一連串多位元組字元。 版本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

參數

pReturnValue
已轉換字串的位元組大小,包括 Null 終止符。

mbstr
所產生之已轉換的多位元組字串的緩衝區位址。

sizeInBytes
mbstr 緩衝區的大小,以位元組為單位。

wcstr
指向要轉換的寬字元字串。

count
要儲存在緩衝區中的 mbstr 位元組數目上限,不包括終止的 Null 字元或 _TRUNCATE

locale
要使用的地區設定。

傳回值

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

錯誤狀況 傳回值和 errno
mbstrNULLsizeInBytes> 0 EINVAL
wcstrNULL EINVAL
目的緩衝區太小,無法包含已轉換的字串 (除非 count_TRUNCATE,請參閱下面的<備註>) ERANGE

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

備註

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

  • 遇到 Null 寬字元

  • 遇到無法轉換的寬字元

  • mbstr 緩衝區中儲存的位元組數目等於 count

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

如果 count 是特殊值 _TRUNCATE,則會 wcstombs_s 將和 符合目的緩衝區一樣多的字串轉換成 ,同時仍保留 Null 終止符的空間。 如果字串遭到截斷,傳回值為 STRUNCATE,而且轉換會視為成功。

如果 wcstombs_s 成功轉換來源字串,則會將已轉換字串的大小以位元組為單位,包括 Null 終止符,放入 *pReturnValue (未提供 pReturnValue NULL)。 即使自變數為 NULL,也會計算mbstr大小;它提供方法來判斷所需的緩衝區大小。 如果 mbstrNULLcount 則會忽略 。

如果 wcstombs_s 遇到無法轉換成多位元組字元的寬字元,則會將 0 *ReturnValue放入 、將目的地緩衝區設定為空字串、將設定 errnoEILSEQ,並傳 EILSEQ回 。

如果 wcstrmbstr 所指向的序列重疊,wcstombs_s 的行為不明。

重要

確定 wcstrmbstr 不會重疊,而且 count 正確反映要轉換的寬字元數。

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

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

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

需求

常式 必要的標頭
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 );
    const 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 - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

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

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}
Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

另請參閱

資料轉換
地區設定
_mbclen、 、 mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte