mbstowcs_s, _mbstowcs_s_l

Article
03/04/2013

Convertit une séquence de caractères codés sur plusieurs octets en une séquence de caractères étendus correspondante.Les versions de mbstowcs, _mbstowcs_l avec les améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du 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
Le nombre de caractères est convertie.
[out] wcstr
Adresse de mémoire tampon pour la chaîne de caractères larges convertie résultante.
[in] sizeInWords
La taille de la wcstr tampon en mots.
[in]mbstr
L'adresse d'une séquence de null terminée par des caractères codés sur plusieurs octets.
[in] count
Le nombre maximal de caractères étendus à stocker dans le wcstr tampon, non compris le caractère null, ou _TRUNCATE.
[in] locale
Les paramètres régionaux à utiliser.

Valeur de retour

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

Condition d'erreur	Valeur de retour eterrno
wcstris NULL and sizeInWords > 0	EINVAL
mbstr est NULL	EINVAL
Le tampon de destination est trop petit pour contenir la chaîne convertie (à moins que count est _TRUNCATE; consultez les remarques ci-dessous)	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

En cas de ces conditions, l'exception du paramètre non valide est appelée comme décrit dans Validation des paramètres .Si l'exécution est autorisée à continuer, la fonction renvoie un code d'erreur et définit errno comme indiqué dans le tableau.

Notes

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

Un caractère multi-octets de null est rencontré.
Un caractère multi-octets non valide est rencontré.
Le nombre de caractères étendus stockées dans la wcstr de la mémoire tampon est égal à count.

La chaîne de destination est toujours nul (même en cas d'erreur).

Si count est la valeur spéciale _TRUNCATE, puis mbstowcs_s convertit autant de la chaîne que tiennent dans la mémoire tampon de destination, tout en laissant place à un terminateur null.

Si mbstowcs_s correctement convertit la chaîne source, il place la taille en caractères étendus de la chaîne convertie, y compris le terminateur null dans *pReturnValue (fourni pReturnValue n'est pas NULL).Ce problème se produit même si le wcstr est de l'argument NULL et offre un moyen pour déterminer la taille de la mémoire tampon requise.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

Si mbstowcs_s rencontre un caractère multioctet non valide, il place 0 dans *pReturnValue, définit la mémoire tampon de destination pour une chaîne vide, jeux de errno à EILSEQet retourne EILSEQ.

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

Note de sécurité
Assurez-vous que wcstr et mbstr ne se chevauchent pas et qui count reflète correctement le nombre de caractères codés sur plusieurs octets à convertir.

mbstowcs_sutilise les paramètres régionaux pour un comportement dépendant des paramètres régionaux ; _mbstowcs_s_lest identique, sauf qu'il utilise les paramètres régionaux passés à la place de.Pour plus d'informations, consultez Paramètres régionaux.

En C++, à l'aide de ces fonctions est simplifiée par des surcharges de modèle ; les surcharges peuvent déduire la longueur du tampon automatiquement (en éliminant le besoin de spécifier un argument size) et ils peuvent remplacer automatiquement des fonctions plus anciennes, non sécurisé avec leurs homologues plus récents et sécurisés.Pour plus d'informations, consultez Surcharges sécurisées de modèle.