mbstowcs_s, _mbstowcs_s_l

Article
06/09/2015

Convertit une séquence de caractères multioctets en une séquence correspondante de caractères larges. Versions de mbstowcs, _mbstowcs_l avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

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

[out] pReturnValue
Nombre de caractères convertis.
[out] wcstr
Adresse de la mémoire tampon du résultat de la conversion de la chaîne de caractères larges.
[in] sizeInWords
La taille de la mémoire tampon wcstr en mots.
[in]mbstr
L'adresse d'une séquence de caractères multioctets terminés par null.
[in] count
Le nombre maximal de caractères larges à stocker dans la mémoire tampon wcstr, à l'exclusion du null de fin, ou _TRUNCATE.
[in] locale
Paramètres régionaux à utiliser.

Valeur de retour

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

Condition d'erreur	Valeur de retour eterrno
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 est _TRUNCATE; consultez les notes ci-dessous)	ERANGE
wcstr n'est NULL et sizeInWords == 0	EINVAL

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

Notes

La fonction mbstowcs_s convertit une chaîne de caractères multioctets pointés par mbstr vers des caractères stockés dans la mémoire tampon désignés par wcstr. La conversion se poursuit pour chaque caractère tant qu'une des conditions suivantes est remplie :

Un caractère NULL multioctets est produit
Un caractères multioctets invalide est produit
Le nombre de caractères larges stockés dans la mémoire tampon wcstr est égale à count.

La chaîne de destination est toujours terminée par null (même en cas d'erreur).

Si count est la valeur spéciale _TRUNCATE, alors mbstowcs_s convertit autant de la chaîne que ce qui s'insérera dans la mémoire tampon de destination, tout en laissant toujours de l'espace pour une marque de fin null.

Si mbstowcs_s convertit correctement la chaîne source, elle définit la taille en caractères larges de la chaîne convertie, notamment la marque de fin null, dans *pReturnValue ( dans la cas où pReturnValue n'est pas NULL). Cela se produit même si l'argument wcstr est NULL et permet de déterminer la taille de mémoire tampon requise. Notez que si wcstr est NULL, count est ignoré, et sizeInWords doit être 0.

Si mbstowcs_s rencontre un caractères multioctets inalide, il renvoie 0 dans *pReturnValue, associe la mémoire tampon de destination à une chaîne vide, définit errno à EILSEQ, et retourne EILSEQ.

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

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

mbstowcs_s utilise les paramètres régionaux actuels pour tout comportement dépend des paramètres régionaux ; _mbstowcs_s_l est identique à la différence qu'il utilise les paramètres régionaux transmis à la place. Pour plus d'informations, consultez Paramètres régionaux.

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 Sécuriser les surcharges de modèle.