`mbsrtowcs_s`

Článek
10/12/2023

Převede řetězec vícebajtového znaku v aktuálním národním prostředí na reprezentaci řetězce širokého znaku. Verze mbsrtowcs s vylepšeními zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Syntaxe

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

Parametry

pReturnValue
Počet převedených znaků.

wcstr
Adresa vyrovnávací paměti pro uložení výsledného převedeného řetězce širokého znaku

sizeInWords
Velikost wcstr slov (široké znaky).

mbstr
Nepřímý ukazatel na umístění vícebajtového znakového řetězce, který se má převést.

count
Maximální počet širokých znaků, které se mají uložit do wcstr vyrovnávací paměti, včetně ukončující hodnoty null nebo _TRUNCATE.

mbstate
Ukazatel na objekt stavu převodu mbstate_t . Pokud je tato hodnota ukazatel null, použije se objekt stavu statického interního převodu. Protože interní mbstate_t objekt není bezpečný pro přístup z více vláken, doporučujeme vždy předat vlastní mbstate parametr.

Vrácená hodnota

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

Chybový stav	Návratová hodnota a `errno`
`wcstr` je ukazatel null a `sizeInWords`> 0	`EINVAL`
`mbstr` je ukazatel null.	`EINVAL`
Řetězec, na který `mbstr` nepřímo odkazuje, obsahuje vícebajtovou sekvenci, která není platná pro aktuální národní prostředí.	`EILSEQ`
Cílová vyrovnávací paměť je příliš malá, aby obsahovala převedený řetězec (pokud `count` není `_TRUNCATE`; další informace viz Poznámky).	`ERANGE`

Pokud dojde k některé z těchto podmínek, je vyvolána neplatná výjimka parametru, jak je popsáno v ověření parametru . Pokud je spuštění povoleno pokračovat, vrátí funkce kód chyby a nastaví errno , jak je uvedeno v tabulce.

Poznámky

Funkce mbsrtowcs_s převede řetězec vícebajtových znaků nepřímo odkazovaných na mbstr široké znaky uložené ve vyrovnávací paměti, na které wcstrodkazuje , pomocí stavu převodu obsaženého v mbstate. Převod bude pokračovat pro každý znak, dokud nebude splněna jedna z těchto podmínek:

Byl zjištěn vícebajtový znak null.
Byl zjištěn neplatný znak s vícebajty.
Počet širokých znaků uložených wcstr ve vyrovnávací paměti se countrovná .

Cílový řetězec wcstr je vždy ukončen s hodnotou null, i když dojde k chybě, pokud wcstr není ukazatel null.

Pokud count je speciální hodnota _TRUNCATE, mbsrtowcs_s převede tolik řetězce, jak se vejde do cílové vyrovnávací paměti, zatímco stále ponechá prostor pro ukončení null.

Pokud mbsrtowcs_s se zdrojový řetězec úspěšně převede, umístí velikost do širokých znaků převedeného řetězce a ukončovací znak null do *pReturnValuezadané pReturnValue hodnoty není nulový ukazatel. Velikost se vypočítá i v případě wcstr , že argument je ukazatel null, který umožňuje určit požadovanou velikost vyrovnávací paměti. Pokud wcstr je ukazatel null, count bude ignorován.

Pokud wcstr není ukazatel null, je objekt ukazatele, na který mbstr odkazuje, přiřazen ukazatel null, pokud převod přestal, protože byl dosažen ukončující znak null. V opačném případě se adresa přiřadí za poslední vícebajtový znak převedený, pokud existuje. Umožňuje následné volání funkce restartovat převod tam, kde se toto volání zastavilo.

Pokud mbstate je ukazatel null, použije se statický objekt stavu interního mbstate_t převodu knihovny. Protože tento interní statický objekt není bezpečný pro přístup z více vláken, doporučujeme předat vlastní mbstate hodnotu.

Pokud mbsrtowcs_s narazí na vícebajtový znak, který není platný v aktuálním národním prostředí, umístí hodnotu -1 do *pReturnValue, nastaví cílovou vyrovnávací paměť wcstr na prázdný řetězec, nastaví errno hodnotu EILSEQa vrátí EILSEQ.

Pokud se sekvence ukazující mbstr na a wcstr překrývají se, chování mbsrtowcs_s není definováno. mbsrtowcs_s je ovlivněna LC_TYPE kategorií aktuálního národního prostředí.

Důležité

Zajistěte, aby wcstr se nepřekrývaly mbstr a aby count správně odrážely počet vícebajtových znaků, které se mají převést.

Funkce mbsrtowcs_s se liší od mbstowcs_smožnosti _mbstowcs_s_l restartování. Stav převodu se uloží mbstate pro následná volání stejných nebo jiných restartovatelných funkcí. Výsledky nejsou definovány při kombinování použití restartovatelných a nerestartovatelných funkcí. Například aplikace by měla místo mbsrlenmbslen, pokud se použije následné volání mbsrtowcs_s místo mbstowcs_s.

V jazyce C++ je použití této funkce zjednodušeno přetížením šablony; přetížení mohou automaticky odvodit délku vyrovnávací paměti (eliminuje požadavek na určení argumentu velikosti) a mohou automaticky nahradit starší, nezabezpečené funkce pomocí novějších zabezpečených protějšků. Další informace naleznete v tématu Přetížení šablon zabezpečení.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Výjimky

Funkce mbsrtowcs_s je vícevláknová, pokud žádná funkce v aktuálním vlákně volá, setlocale pokud se tato funkce spouští a mbstate argument není ukazatelem null.

Požadavky

Rutina	Požadovaný hlavičkový soubor
`mbsrtowcs_s`	<wchar.h>

Viz také

Převod dat
Národní prostředí
Interpretace vícebajtových sekvencí znaků
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit

Share via