wcstombs_s, _wcstombs_s_l

Article
06/09/2015

Convertit la séquence de caractères multioctets en la séquence correspondante de caractères larges. Il s'agit de versions de wcstombs, _wcstombs_l avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le 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
Nombre de caractères convertis.
[out] mbstr
L'adresse d'un tampon pour la chaîne de caractères multioctets convertie résultante.
[in]sizeInBytes
La taille en octets de la mémoire tampon mbstr.
[in] wcstr
Pointe vers la chaîne de caractères larges à convertir.
[in] count
Le nombre maximal de caractères larges à stocker dans la mémoire tampon mbstr, à l'exclusion du null de fin, ou _TRUNCATE.
[in] locale
Paramètres régionaux à utiliser.

Valeur de retour

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

Condition d'erreur	Valeur de retour eterrno
mbstr est NULL et sizeInBytes >	EINVAL
wcstr est NULL	EINVAL
La mémoire tampon de destination est trop petite pour contenir la chaîne convertie (à moins que count est _TRUNCATE; consultez les notes ci-dessous)	ERANGE

Si l'une de ces conditions d'erreur se produit, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à continuer, la fonction retourne un code d'erreur et définit errno comme indiqué dans la table.

Notes

La fonction wcstombs_s convertit une chaîne de caractères multioctets pointés par wcstr vers des caractères stockés dans la mémoire tampon désignés par mbstr. La conversion se poursuit pour chaque caractère tant qu'une des conditions suivantes est remplie :

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

La chaîne de destination est toujours terminée par null (même en cas d'erreur).

Si count est la valeur spéciale _TRUNCATE, alors wcstombs_s convertit autant de la chaîne que ce qui s'insérera dans la mémoire tampon de destination, tout en laissant toujours de l'espace pour une marque de fin null.

Si wcstombs_s convertit correctement la chaîne source, elle définit la taille en octets de la chaîne convertie, notamment la marque de fin null, dans *pReturnValue ( dans la cas où pReturnValue n'est pas NULL). Cela se produit même si l'argument mbstr est NULL et permet de déterminer la taille de mémoire tampon requise. Notez que si mbstr est NULL, count est ignoré.

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

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

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

wcstombs_s utilise les paramètres régionaux actuels pour tout comportement dépendant des paramètres régionaux ; _wcstombs_s_l est identique à wcstombs à l'exception qu'il utilise les paramètres régionaux transmis à la place. Pour plus d'informations, consultez Paramètres régionaux.

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.

Configuration requise

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

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

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 );
    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);
    }
}