共用方式為


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

參數

  • [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);
    }
}
  

.NET Framework 對等用法

不適用。若要呼叫標準 C 函式,請使用 PInvoke。如需詳細資訊,請參閱平台叫用範例

請參閱

參考

資料轉換

地區設定

_mbclen、mblen、_mblen_l

mbstowcs、_mbstowcs_l

mbtowc、_mbtowc_l

wctomb_s、_wctomb_s_l

WideCharToMultiByte