wcstombs_s _wcstombs_s_l

Článek
03/04/2013

Posloupnost znaků široké převede na odpovídající posloupnost vícebajtových znaků.Verze wcstombs _wcstombs_l s vylepšení zabezpečení popsaným v Funkce zabezpečení v 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

Parametry

[výstup]pReturnValue
Počet znaků, které jsou převedeny.
[výstup]mbstr
Adresa vyrovnávací paměti pro výsledný řetězec převedený vícebajtových znaků.
[v]sizeInBytes
Velikost v bajtech mbstr vyrovnávací paměti.
[v]wcstr
Body převést řetězec znaků.
[v]count
Maximální počet znaků široké uložené v mbstr vyrovnávací paměti není včetně ukončujícím znakem null nebo _TRUNCATE.
[v]locale
Národní prostředí použít.

Vrácená hodnota

Nula, pokud je úspěšná, kód chyby při selhání.

Chybový stav	Vrátí hodnotu aerrno
mbstris NULL and sizeInBytes > 0	EINVAL
wcstrjeNULL	EINVAL
Cílové vyrovnávací paměti je příliš malá, obsahovat řetězec převedený (Pokud count je _TRUNCATE; viz poznámky níže)	ERANGE

Pokud dojde k některé z těchto podmínek, je neplatný parametr výjimky vyvolat popsaným v Ověření parametrů .Pokud je povoleno spuštění pokračovat, vrátí kód chyby a nastaví errno jak je uvedeno v tabulce.

Poznámky

wcstombs_s Funkce převede řetězec znaků široký, na kterou odkazuje wcstr do vícebajtových znaků uložených ve vyrovnávací paměti, na kterou odkazuje mbstr.Převod bude pro každý znak pokračovat, dokud není splněna jedna z těchto podmínek:

Je-li zjištěna širokým znakem null
Je-li zjištěna široký znak, který nelze převést
Počet bajtů, které jsou uloženy v mbstr vyrovnávací paměti se rovná count.

Cíl řetězec je vždy zakončený (i u chyba).

Pokud count je speciální hodnota _TRUNCATE, pak wcstombs_s převede část řetězce jako se vejdou do vyrovnávací paměti cíl, přitom stále ponechat prostor pro zakončení null.

Pokud wcstombs_s úspěšně převede řetězec zdroje systémem je velikost v bajtech převedeného řetězec, včetně ukončovací null do *pReturnValue (podle pReturnValue není NULL).Dochází i v případě mbstr argument je NULL a poskytuje způsob, jak určit velikost použité vyrovnávací paměti.Note that if mbstr is NULL, count is ignored.

Pokud wcstombs_s nalezne širokými znaky nelze převést na vícebajtové znakové ji umístí 0 *pReturnValue, nastaví cílové vyrovnávací paměti na prázdný řetězec, nastaví errno na EILSEQa vrátí EILSEQ.

Pokud na sekvence odkazuje wcstr a mbstr překrývají, chování wcstombs_s nedefinovaná.

Poznámka k zabezpečení
Zajistit, aby wcstr a mbstr nepřekrývají a že count správně odráží počet znaků široké převést.

wcstombs_spoužívá aktuální národní prostředí pro všechny národní prostředí závislé na chování; _wcstombs_s_lje shodné s wcstombs až na to, že používá místo předaný národní prostředí.Další informace naleznete v tématu Národní prostředí.

V jazyce C++ použití těchto funkcí je zjednodušeno díky šablony přetížení; přetížení automaticky odvodit vyrovnávací paměti (není tak nutné zadat argument velikost) a jsou automaticky nahradit starší, -secure funkce s jejich protějšky novější, zabezpečené.Další informace naleznete v tématu Přetížení šablony zabezpečení.

Požadavky

Rutina	Požadované záhlaví
wcstombs_s	<stdlib.h>

Další informace o kompatibilitě, viz Compatibility v úvodu.

Příklad

Tento program popisuje chování wcstombs_s funkce.

// 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);
    }
}