wcstombs_s, _wcstombs_s_l

Article
03/04/2013

convertit une séquence de caractères larges à une séquence correspondante de caractères multioctets.Une version de wcstombs, _wcstombs_l avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

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

[out] pReturnValue
Le nombre de caractères convertis.
[out] mbstr
L'adresse d'une mémoire tampon pour la chaîne à caractères multioctets convertie résultante.
[in]sizeInBytes
la taille en octets de la mémoire tampon d' mbstr .
[in] wcstr
Pointe sur la chaîne à caractères larges à convertir.
[in] count
Le nombre maximal de caractères larges à stocker dans la mémoire tampon d' mbstr , sans le caractère NULL de fin, ou _TRUNCATE.
[in] locale
Les paramètres régionaux à utiliser.

Valeur de retour

Zéro en cas de réussite, le code d'erreur en cas de é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 qu' count est _TRUNCATE; voir notes ci-dessous)	ERANGE

Si l'un de ces conditions se produit, l'exception de paramètre non valide est appelée comme décrit dans Validation des paramètres .Si est autorisé à l'exécution de se poursuivre, la fonction retourne un code d'erreur et définit errno comme indiqué dans le tableau.

Notes

La fonction d' wcstombs_s convertit une chaîne de caractères larges entrées figurant dans wcstr dans des caractères multioctets stockés en mémoire tampon désignée par mbstr.La conversion continuera pour chaque caractère jusqu'à ce que l'une des conditions suivantes est remplie :

Un caractère élargi null est produit
Un caractère élargi qui ne peut pas être converti est produit
Le nombre d'octets stockés en mémoire tampon d' mbstr égale count.

La chaîne de destination est toujours se terminant par null (même dans le cas d'une erreur).

Si count est la valeur spéciale _TRUNCATE, alors wcstombs_s convertit autant de la chaîne que correspondra dans la mémoire tampon de destination, tout en quittant toujours la place pour une marque de fin null.

Si wcstombs_s convertit correctement la chaîne source, il met la taille en octets de la chaîne convertie, y compris le terminateur null, dans *pReturnValue ( pReturnValue fourni n'est pas NULL).Cela se produit même si l'argument d' mbstr est NULL et fournit une méthode pour déterminer la taille de la mémoire tampon requise.notez que si mbstr est NULL, count est ignoré.

Si wcstombs_s rencontre un caractère élargi qu'il ne peut pas convertir en un caractère multioctets, il met 0 dans *pReturnValue, définit la mémoire tampon de destination à une chaîne vide, définit errno à EILSEQ, et retourne EILSEQ.

Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement d' wcstombs_s n'est pas défini.

Note de sécurité
Assurez -vous qu' wcstr et mbstr ne se chevauchent pas, et qu' count reflète correctement le nombre de caractères larges pour convertir.

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

En C++, à l'aide de ces fonctions est simplifié par des surcharges de modèle ; les surcharges peuvent également déduire la longueur de la mémoire tampon automatiquement (en éliminant le besoin de spécifier un argument de taille) et peuvent remplacer automatiquement des fonctions plus anciennes et non sécurisées par leurs nouvelles, sécurisées équivalents.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Configuration requise

routine	en-tête requis
wcstombs_s	<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_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 );
    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 );

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

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