`mbsrtowcs_s`

Article
10/12/2023

Convertir une chaîne de caractères multioctets correspondant aux paramètres régionaux actuels en sa représentation sous forme de chaîne de caractères larges. Version des améliorations de mbsrtowcs sécurité décrites dans les fonctionnalités de sécurité du CRT.

Syntaxe

errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t * wcstr,
   size_t sizeInWords,
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
);
template <size_t size>
errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t (&wcstr)[size],
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
); // C++ only

Paramètres

pReturnValue
Nombre de caractères convertis.

wcstr
Adresse de la mémoire tampon où stocker la chaîne de caractères larges convertie.

sizeInWords
La taille de wcstr en mots (caractères étendus).

mbstr
Pointeur indirect vers l'emplacement de la chaîne de caractères multioctets à convertir.

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

mbstate
Un pointeur vers un objet d'état de conversion mbstate_t. Si cette valeur est un pointeur null, un objet d'état de conversion interne statique est utilisé. Étant donné que l’objet interne mbstate_t n’est pas thread-safe, nous vous recommandons de toujours passer votre propre mbstate paramètre.

Valeur retournée

Zéro si la conversion est réussie, ou un code d'erreur en cas d'échec.

Condition d’erreur	Valeur de retour et `errno`
`wcstr` est un pointeur Null et `sizeInWords`> 0	`EINVAL`
`mbstr` est un pointeur Null	`EINVAL`
La chaîne indirectement pointée par `mbstr` contient une séquence multioctet qui n’est pas valide pour les paramètres régionaux actuels.	`EILSEQ`
La mémoire tampon de destination est trop petite pour contenir la chaîne convertie (à moins que `count` ait la valeur `_TRUNCATE` ; pour plus d'informations, consultez les notes ci-dessous).	`ERANGE`

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 mbsrtowcs_s convertit une chaîne de caractères multioctets indirectement pointée par mbstr en caractères larges stockés dans la mémoire tampon pointée par wcstr, en utilisant l'état de conversion contenu dans mbstate. 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 wcstr de destination est toujours terminée par null, même en cas d’erreur, sauf s’il wcstr s’agit d’un pointeur Null.

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

Si mbsrtowcs_s elle convertit correctement la chaîne source, elle place la taille en caractères larges de la chaîne convertie et le pointeur de fin Null en *pReturnValue, fourni pReturnValue n’est pas un pointeur Null. La taille est calculée même si l’argument wcstr est un pointeur Null, ce qui vous permet de déterminer la taille de mémoire tampon requise. S’il wcstr s’agit d’un pointeur Null, count il est ignoré.

Si wcstr ce n’est pas un pointeur Null, l’objet pointeur vers lequel pointe mbstr un pointeur null est affecté si la conversion s’est arrêtée, car un caractère null de fin a été atteint. Sinon, il est affecté à l’adresse juste après le dernier caractère multioctet converti, le cas échéant. Elle permet à un appel de fonction suivant de redémarrer la conversion où cet appel s’est arrêté.

Si mbstate est un pointeur Null, l'objet statique d'état de la conversion mbstate_t interne de la bibliothèque est utilisé. Étant donné que cet objet statique interne n’est pas thread-safe, nous vous recommandons de passer votre propre mbstate valeur.

Si mbsrtowcs_s un caractère multioctet n’est pas valide dans les paramètres régionaux actuels, il place -1 dans *pReturnValue, définit la mémoire tampon wcstr de destination sur une chaîne vide, définit errno la EILSEQvaleur et renvoie EILSEQ.

Si les séquences pointées par mbstr et wcstr se chevauchent, le comportement de mbsrtowcs_s n'est pas défini. mbsrtowcs_s est affecté par la LC_TYPE catégorie des paramètres régionaux actuels.

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 mbsrtowcs_s fonction diffère de , _mbstowcs_s_l par mbstowcs_ssa capacité de redémarrage. L'état de la conversion est stocké dans mbstate pour les appels suivants à la même ou à d'autres fonctions redémarrables. Les résultats ne sont pas définis quand l'utilisation de fonctions redémarrables est combinée avec l'utilisation de fonctions non redémarrables. Par exemple, une application doit utiliser mbsrlen au lieu de mbslen, si un appel ultérieur est mbsrtowcs_s utilisé au lieu de mbstowcs_s.

En C++, l’utilisation de cette fonction est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire automatiquement la longueur de la mémoire tampon (éliminant la nécessité de spécifier un argument de taille) et elles peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées à l’aide des équivalents plus récents et sécurisés. 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.

Exceptions

La mbsrtowcs_s fonction est multithread safe si aucune fonction dans les appels setlocale de thread actuel tant que cette fonction est en cours d’exécution et que l’argument mbstate n’est pas un pointeur Null.

Spécifications

Routine	En-tête requis
`mbsrtowcs_s`	<wchar.h>

Voir aussi

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit

Partager via