wcstombs, _wcstombs_l

Article
03/04/2013

convertit une séquence de caractères larges à une séquence correspondante de caractères multioctets.plus les versions 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
Nombre maximal d'octets qui peuvent être stockés dans la chaîne multioctets de sortie.
locale
Les paramètres régionaux à utiliser.

Valeur de retour

Si wcstombs convertit correctement la chaîne multioctets, il retourne le nombre d'octets entrés dans la chaîne multioctets de sortie, à l'exclusion d' NULL de fin (le cas échéant).Si l'argument d' mbstr est NULL, wcstombs retourne la taille requise en octets de la chaîne de destination.Si wcstombs rencontre un caractère élargi qu'il ne peut pas convertir en un caractère multioctets, il retourne - 1 cast en type size_t et définit errno à EILSEQ.

Notes

La fonction d' wcstombs convertit la chaîne à caractères larges désignée par wcstr aux caractères multioctets correspondants et stocke les résultats dans le tableau d' mbstr .Le paramètre d' count indique le nombre maximal d'octets qui peuvent être stockés dans la chaîne multioctets de sortie (autrement dit, la taille d' mbstr).En général elle n'est pas connue le nombre d'octets sont requis lorsque vous convertissez une chaîne à caractères larges.Certains caractères larges auront besoin d'un octet dans la chaîne de sortie ; d'autres nécessitent deux.S'il y a deux octets dans la chaîne multioctets de sortie pour chaque caractère élargi dans la chaîne d'entrée (caractère élargi y compris NULL), le résultat est garanti pour s'adapter.

Si wcstombs rencontre le caractère NULL à caractères larges (L \ 0 ') ou avant ou lorsque count se produit, il convertit en 0 de 8 bits et s'arrête.Ainsi, la chaîne à caractères multioctets à l'adresse mbstr se terminant par null uniquement si wcstombs rencontre un caractère Null à caractère élargi pendant la conversion.Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement d' wcstombs n'est pas défini.

Si l'argument d' mbstr est NULL, wcstombs retourne la taille requise en octets de la chaîne de destination.

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

wcstombs utilise les paramètres régionaux définis pour tout comportement dépendant des paramètres régionaux ; _wcstombs_l est identique mais il utilise les paramètres régionaux passés à la place.Pour plus d'informations, consultez Paramètres régionaux.

En C++, ces fonctions ont des surcharges de modèle qui appellent plus le nouveau, sécuriser des équivalents de ces fonctions.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Configuration requise

routine	en-tête requis
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

Pour des informations de compatibilité supplémentaires, consultez compatibilité dans l'introduction.

Exemple

ce programme illustre le comportement de la fonction d' 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);
}