mbsrtowcs

Convertit une chaîne de caractères multioctets dans les paramètres régionaux actuels en une chaîne de caractères larges correspondante, avec la capacité de redémarrer au milieu d'un caractère multioctet. Une version plus sécurisée de cette fonction est disponible ; voir mbsrtowcs_s.

Syntaxe

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

Paramètres

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

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

count
Nombre maximal de caractères (et non pas d'octets) à convertir et à stocker dans wcstr.

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

Retourne le nombre de caractères correctement convertis, non compris le caractère null de fin, le cas échéant. Retourne (size_t)(-1) si une erreur s’est produite et est la valeur errno EILSEQ.

Notes

La fonction mbsrtowcs 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’un caractère multioctet null soit terminé, une séquence multioctet qui ne correspond pas à un caractère valide dans les paramètres régionaux actuels soit rencontrée, soit jusqu’à ce que count les caractères aient été convertis. Si mbsrtowcs rencontre le caractère null multioctet (« \0 ») avant ou au moment où count est atteint, elle le convertit en un caractère null de fin sur 16 bits et s'arrête.

Par conséquent, la chaîne de caractères larges dans wcstr est terminée par un caractère null seulement si mbsrtowcs rencontre un caractère null multioctet pendant la conversion. Si les séquences pointées par mbstr et wcstr se chevauchent, le comportement de mbsrtowcs n'est pas défini. mbsrtowcs est affecté par la LC_TYPE catégorie des paramètres régionaux actuels.

La mbsrtowcs fonction diffère de , _mbstowcs_l par mbstowcssa 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 utilisé au lieu de mbstowcs.

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 l’argument wcstr est un pointeur Null, l’argument count est ignoré et mbsrtowcs retourne la taille requise en caractères larges pour la chaîne de destination. Si mbstate est un pointeur null, la fonction utilise un objet d'état de conversion mbstate_t interne statique qui n'est pas thread-safe. Si la séquence mbstr de caractères n’a pas de représentation de caractère multioctet correspondante, un -1 est retourné et errno est défini sur EILSEQ.

Si mbstr est un pointeur null, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, cette fonction affecte à errno la valeur EINVAL et retourne -1.

En C++, cette fonction a une surcharge de modèle qui appelle l'équivalent plus récent et sécurisé de cette fonction. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

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 fonction est sécurisée multithread tant qu’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

Voir aussi

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