Partager via


mbstowcs_s, _mbstowcs_s_l

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é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.

Configuration requise

Routine

En-tête requis

mbstowcs_s

<stdlib.h>

_mbstowcs_s_l

<stdlib.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité dans l'introduction.

Équivalent .NET Framework

Non applicable. Pour appeler la fonction C standard, utilisez PInvoke. Pour plus d'informations, consultez Exemples d'appel de plateforme.

Voir aussi

Référence

Conversion de données

Paramètres régionaux

Interprétation des séquences de caractères multioctets

_mbclen, mblen, _mblen_l

mbtowc, _mbtowc_l

wcstombs, _wcstombs_l

wctomb, _wctomb_l