mbstowcs_s, _mbstowcs_s_l

Convertit une séquence de caractères multioctets en séquence correspondante de caractères larges. Versions de , _mbstowcs_lavec améliorations dembstowcs sécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.

Syntaxe

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Paramètres

pReturnValue
Nombre de caractères convertis.

wcstr
Adresse de la mémoire tampon pour la chaîne de caractères larges convertie résultante.

sizeInWords
Taille, en mots, de la mémoire tampon wcstr.

mbstr
Adresse d’une séquence de caractères multioctets se terminant par un caractère Null.

count
Nombre maximal de caractères larges à stocker dans la wcstr mémoire tampon, sans inclure la valeur Null de fin, ou _TRUNCATE.

locale
Paramètres régionaux à utiliser.

Valeur retournée

Zéro si l'opération a réussi, un code d'erreur en cas d'échec.

Condition d’erreur	Valeur de retour et errno
wcstr est NULL et sizeInWords> 0	EINVAL
mbstr est NULL	EINVAL
La mémoire tampon de destination est trop petite pour contenir la chaîne convertie (à moins que count ait la valeur _TRUNCATE ; consultez les notes ci-dessous)	ERANGE
wcstr n’est pas NULL et sizeInWords == 0	EINVAL

Si l’une de ces conditions se produit, l’exception de paramètre non valide est appelée comme décrit dans la validation des paramètres. Si l'exécution est autorisée à continuer, la fonction retourne un code d'erreur et définit errno, comme indiqué dans le tableau.

Notes

La fonction mbstowcs_s convertit une chaîne de caractères multioctets désignés par mbstr en caractères larges stockés dans la mémoire tampon désignée par wcstr. La conversion se poursuit pour chaque caractère jusqu'à ce qu'une des conditions suivantes soit remplie :

• Un caractère multioctet de null est rencontré.

• Un caractère multioctet non valide est rencontré.

• Le nombre caractères larges stockés dans la mémoire tampon de wcstr est égal à count.

La chaîne de destination est toujours terminée par null (même s’il existe une erreur).

S’il count s’agit de la valeur _TRUNCATEspéciale, mbstowcs_s convertit autant de chaînes que dans la mémoire tampon de destination, tout en laissant la place pour un terminateur Null.

Si mbstowcs_s elle convertit correctement la chaîne source, elle place la taille en caractères larges de la chaîne convertie, y compris la marque de fin Null, dans *pReturnValue (fournie pReturnValue n’est pas NULL). La taille est calculée même si l’argument wcstr est NULL, et fournit un moyen de déterminer la taille de mémoire tampon requise. Si wcstr c’est NULLle cas, count est ignoré et sizeInWords doit être 0.

Si la fonction mbstowcs_s rencontre un caractère multioctet non valide, elle affecte la valeur 0 à *pReturnValue, définit la mémoire tampon de destination sur une chaîne vide, affecte à errno la valeur EILSEQ et retourne EILSEQ.

Si les séquences pointées par mbstr et wcstr se chevauchent, le comportement de mbstowcs_s n'est pas défini.

Important

Vérifiez que wcstr et mbstr ne se chevauchent pas, et que count reflète correctement le nombre de caractères multioctets à convertir.

La fonction mbstowcs_s utilise les paramètres régionaux actuels pour tout comportement dépendant des paramètres régionaux ; la fonction _mbstowcs_s_l est identique, à ceci près qu’elle utilise à la place les paramètres régionaux qui ont été passés. Pour plus d’informations, consultez Locale.

En C++, l’utilisation de ces fonctions est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire la longueur de la mémoire tampon automatiquement (ce qui évite d’avoir à spécifier un argument taille) et peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalentes plus récentes et sécurisées. Pour plus d’informations, consultez Surcharges de modèles sécurisés.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Spécifications

Routine	En-tête requis
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Voir aussi

Conversion de données
Paramètres régionaux
MultiByteToWideChar
Interprétation des séquences de caractères multioctets
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l