mbstowcs_s, _mbstowcs_s_l

 

Pour obtenir la dernière documentation sur Visual Studio 2017, consultez Documentation Visual Studio 2017.

Convertit une séquence de caractères multioctets en une séquence de caractères larges correspondante. Versions de mbstowcs, _mbstowcs_l avec des améliorations de sécurité comme décrit dans fonctionnalités de sécurité de la bibliothèque 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 pour la chaîne de caractères larges convertie résultante.

[in] sizeInWords
La taille de la wcstr tampon dans les mots.

[in]mbstr
L’adresse d’une séquence de null s’est arrêté de caractères multioctets.

[in] count
Le nombre maximal de caractères larges à stocker dans le wcstr tampon, non compris le caractère null de fin, ou _TRUNCATE.

[in] locale
Paramètres régionaux à utiliser.

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

Condition d'erreurValeur de retour et errno
wcstr a la valeur NULL et sizeInWords > 0EINVAL
mbstr a la valeur 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
wcstris not NULL and sizeInWords == 0EINVAL

Si une des conditions suivantes se produit, l’exception de paramètre non valide est appelée 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 le tableau.

Le mbstowcs_s fonction convertit une chaîne de caractères multioctets pointé par mbstr en caractères larges stockés dans la mémoire tampon pointé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 en cas d'erreur).

Si count est la valeur spéciale _TRUNCATE, puis mbstowcs_s convertit la chaîne selon tenir dans la mémoire tampon de destination, tout en laissant la place pour une marque de fin null.

Si mbstowcs_s convertit correctement la chaîne source, elle place la taille en caractères étendus de la chaîne convertie, y compris le terminateur null, en *``pReturnValue (fourni pReturnValue n’est pas NULL). Cela se produit même si l'argument wcstr a la valeur NULL, et permet de déterminer la taille de mémoire tampon requise. Notez que si wcstr est NULL, count est ignorée, et sizeInWords doit être 0.

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

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

System_CAPS_ICON_important.jpg Important

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

mbstowcs_sutilise les paramètres régionaux actuels pour tout comportement dépendant des paramètres régionaux ; _mbstowcs_s_l est identique, sauf qu’elle utilise les paramètres régionaux passé à la place. 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 Secure Template Overloads.

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

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

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

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

Afficher: