`wcsrtombs_s`

Article
10/12/2023

Convertit une chaîne de caractères larges dans sa représentation de chaîne de caractères multioctets. Version des améliorations de wcsrtombs sécurité décrites dans les fonctionnalités de sécurité du CRT.

Syntaxe

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

Paramètres

pReturnValue
Taille en octets de la chaîne convertie, y compris la marque de fin Null.

mbstr
Adresse d'une mémoire tampon pour la chaîne de caractères multioctets convertie résultante.

sizeInBytes
Taille en octets de la mémoire tampon mbstr.

wcstr
Pointe vers la chaîne de caractères larges à convertir.

count
Nombre maximal d’octets à stocker dans la mbstr mémoire tampon, ou _TRUNCATE.

mbstate
Un pointeur vers un objet d'état de conversion mbstate_t.

Valeur retournée

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

Condition d’erreur	Valeur de retour et `errno`
`mbstr` est `NULL` et `sizeInBytes`> 0	`EINVAL`
`wcstr` est `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`

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 wcsrtombs_s convertit une chaîne de caractères larges vers laquelle pointe wcstr en caractères multioctets stockés dans la mémoire tampon vers laquelle pointe mbstr, en utilisant l’état de conversion indiqué dans mbstate. La conversion se poursuit pour chaque caractère jusqu'à ce qu'une des conditions suivantes soit remplie :

Un caractère large null est rencontré
Un caractère large qui ne peut pas être converti est rencontré
Le nombre d'octets stockés dans la mémoire tampon mbstr est égal à count.

La chaîne de destination est toujours terminée par null (même s’il existe une erreur).

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

Si wcsrtombs_s elle convertit correctement la chaîne source, elle place la taille en octets de la chaîne convertie, y compris le terminateur Null, dans *pReturnValue (fourni pReturnValue n’est pas NULL). La taille est calculée même si l’argument mbstr est NULL; il permet de déterminer la taille de mémoire tampon requise. Si mbstr c’est NULLle cas, count est ignoré.

Si wcsrtombs_s vous rencontrez un caractère large, il ne peut pas convertir en caractère multioctet, il place -1 dans , définit la mémoire tampon de destination sur *pReturnValueune chaîne vide, définit errno sur EILSEQet renvoie EILSEQ.

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

Important

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

La wcsrtombs_s fonction diffère de , _wcstombs_s_l par wcstombs_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 utiliserait wcsrlen plutôt que wcslen si un appel ultérieur à wcsrtombs_s était utilisé à la place de wcstombs_s.

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 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 fonction wcsrtombs_s est multithread-safe tant qu’aucune fonction du thread actif n’appelle setlocale pendant l’exécution de cette fonction et que mbstate a la valeur Null.

Exemple

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Spécifications

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

Voir aussi

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Share via