wcstombs, _wcstombs_l

Article
06/09/2015

Convertit la séquence de caractères multioctets en la séquence correspondante de caractères larges. Des versions plus sécurisées de ces fonctions sont disponibles ; consultez wcstombs_s, _wcstombs_s_l.

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Paramètres

mbstr
L'adresse d'une séquence de caractères multioctets.
wcstr
L'adresse d'une séquence de caractères larges.
count
Le nombre maximal d'octets qui peuvent être stockés dans la chaîne de sortie multioctets.
locale
Paramètres régionaux à utiliser.

Valeur de retour

Si wcstombs convertit correctement la chaîne multioctets, elle retourne le nombre d'octets écrits dans la chaîne de sortie multioctets, à l'exception du NULL de fin (le cas échéant). Si l'argument mbstr est NULL, wcstombs retourne la taille requise en octets de la chaine de destination. Si wcstombs rencontre un caractère large qu'il ne peut pas convertir en caractères multioctets, il retourne – 1 converti en type size_t et définit errno à EILSEQ.

Notes

La fonction wcstombs convertit la chaîne de caractères larges désignée par wcstr en les caractères multioctets correspondants et stocke les résultats dans le tableau mbstr. Le paramètre count indique le nombre maximal d'octets qui peuvent être stockés dans la chaîne de sortie multioctets (autrement dit, la taille de mbstr). En général, on ne sait pas combien d'octets sont requis quand on convertit une chaîne de caractères larges. Certains caractères larges ont besoin d'un seul octet dans la chaîne de sortie ; d'autres nécessitent deux. S'il existe deux octets dans la chaîne de sortie multioctets pour chaque caractère large dans la chaîne d'entrée caractère large (y compris le caractère large NULL), le résultat est garanti de s'ajuster.

Si wcstombs rencontre le caractère NULL de caractères étendus (L '\0) avant ou lorsque count arrive, il le convertit en un 0 de 8 bits et s'arrête. Par conséquent, la chaîne de caractères multioctets à mbstr se termine par null uniquement si wcstombs rencontre un caractère NULL de caractères larges lors de la conversion. Si les séquences désignées par wcstr et mbstr se chevauchent, le comportement de wcstombs n'est pas défini.

Si l'argument mbstr est NULL, wcstombs retourne la taille requise en octets de la chaine de destination.

wcstombs valide ses paramètres. Si wcstr est NULL, ou si count est supérieur àINT_MAX, cette fonction appelle le gestionnaire de paramètre non valide, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, la fonction définit errno à la valeur EINVAL et retourne -1.

wcstombs utilise les paramètres régionaux actuels pour tout comportement dépend des paramètres régionaux ; _wcstombs_l est identique à la différence qu'il utilise les paramètres régionaux transmis à la place. Pour plus d'informations, consultez Paramètres régionaux.

En C++, ces fonctions ont des surcharges de modèle qui appellent les équivalents plus récents et sécurisés de ces fonctions. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Configuration requise

Routine	En-tête requis
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

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

Exemple

Ce programme illustre le comportement de la fonction wcstombs.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

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

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

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}