共用方式為

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
mbstr 是 NULL 和 sizeInBytes> 0 EINVAL
wcstr 是 NULL 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大小;它提供方法來判斷所需的緩衝區大小。 如果 mbstr 為 NULL， count 則會忽略 。

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

如果 wcstr 和 mbstr 所指向的序列重疊，wcstombs_s 的行為不明。

重要

確定 wcstr 和 mbstr 不會重疊，而且 count 正確反映要轉換的寬字元數。

wcstombs_s 會針對任何與地區設定相關的行為使用目前的地區設定，_wcstombs_s_l 與 wcstombs 相同，只不過它會改用傳入的地區設定。 如需詳細資訊，請參閱 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