wcstombs_s, _wcstombs_s_l

Convertit une séquence de caractères larges en une séquence correspondante de caractères multioctets. Une version de , _wcstombs_lavec des améliorations dewcstombs sécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.

Syntaxe

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // 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, sans inclure le caractère null de fin, ou _TRUNCATE.

locale
Paramètres régionaux à utiliser.

Valeur retournée

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

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 wcstombs_s convertit une chaîne de caractères larges pointés par wcstr en caractères multioctets stockés dans la mémoire tampon pointée par mbstr. 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, wcstombs_s convertit autant de chaînes que dans la mémoire tampon de destination, tout en laissant la place pour un terminateur Null. Si la chaîne est tronquée, la valeur de retour est STRUNCATE, et la conversion est considérée comme réussie.

Si wcstombs_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 wcstombs_s vous rencontrez un caractère large, il ne peut pas convertir en caractère multioctet, il place 0 dans *ReturnValue, définit la mémoire tampon de destination sur une 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 wcstombs_s n'est pas défini.

La fonction wcstombs_s utilise les paramètres régionaux actuels pour tout comportement dépendant des paramètres régionaux ; la fonction _wcstombs_s_l est identique à wcstombs sauf qu'elle utilise les paramètres régionaux passés à 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 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.

Spécifications

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple

Ce programme illustre le comportement de la fonction wcstombs_s.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t i;
    char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    const wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

Voir aussi

Conversion de données
Paramètres régionaux
_mbclen, , mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte