wcsrtombs_s

發行項
02/28/2013

將寬字元字串轉換成它的多位元組字元的字串表示。版本的wcsrtombs中所述的安全性增強功能與安全性功能，則在 CRT 中。

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

參數

[out] pReturnValue
轉換的字元數。
[out] mbstr
產生的已轉換的多位元組字元字串緩衝區的位址。
[out] sizeInBytes
以位元組為單位的大小mbstr的緩衝區。
[in] wcstr
寬字元字串，以指定須轉換的點。
[in] count
最大的數字的位元組，並儲存在mbstr的緩衝區，或_TRUNCATE。
[in] mbstate
變數的指標， mbstate_t轉換狀態物件。

傳回值

零，如果執行成功、失敗的錯誤代碼。

錯誤狀況	傳回值，errno
mbstris NULL and sizeInBytes > 0	EINVAL
wcstr 為 NULL	EINVAL
目的緩衝區是太小無法包含轉換後的字串 (除非count是_TRUNCATE。請參閱下方註解)	ERANGE

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

備註

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

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

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

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

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

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

如果所指的序列wcstr和mbstr重疊，行為的wcsrtombs_s尚未定義。 wcsrtombs_s會影響目前的地區設定中的 [LC_TYPE] 類別。

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

wcsrtombs_s函式會不同於wcstombs_s _wcstombs_s_l由其重新。轉換狀態儲存在mbstate進行後續的呼叫至相同或其他可重新啟動的功能。混合的重新啟動的和即可函式使用時，結果是未定義。例如，應用程式會使用wcsrlen而不是wcslen，如果的後續呼叫wcsrtombs_s而不是使用wcstombs_s.

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

例外狀況

wcsrtombs_s函式為多執行緒的安全，只要在目前的執行緒中的函式會呼叫setlocale這個函式執行時， mbstate為 null。

範例

// crt_wcsrtombs_s.cpp
// 
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

void main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfully converted.\n" );
    }
}