wcstombs_s, _wcstombs_s_l

 

Date de publication : novembre 2016

Pour obtenir la dernière documentation sur Visual Studio 2017 RC, consultez Documentation Visual Studio 2017 RC.

Convertit une séquence de caractères larges en 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é de la bibliothèque 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
Adresse d'une mémoire tampon pour la chaîne de caractères multioctets convertie résultante.

[in]sizeInBytes
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 d’octets à stocker dans le mbstr tampon, non compris le caractère null de fin, ou _TRUNCATE.

[in] locale
Paramètres régionaux à utiliser.

Zéro si l’opération réussit, un code d’erreur en cas d’échec.

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

Si une des conditions suivantes se produit, l’exception de paramètre non valide est appelée 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 le tableau.

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 en cas d'erreur).

Si count est la valeur spéciale _TRUNCATE, puis wcstombs_s convertit la chaîne selon tenir dans la mémoire tampon de destination, tout en laissant la place pour une marque de fin null.

Si wcstombs_s convertit correctement la chaîne source, elle place la taille en octets de la chaîne convertie, y compris le terminateur null, en *``pReturnValue (fourni pReturnValue n’est pas NULL). Cela se produit même si l'argument mbstr a la valeur NULL, et permet de déterminer la taille de mémoire tampon requise. Notez que si mbstr a la valeur NULL, le paramètre count est ignoré.

Si wcstombs_s rencontre un caractère large, elle ne peut pas convertir en caractères multioctets, elle affecte la valeur 0 *``pReturnValue, définit la mémoire tampon de destination avec une chaîne vide, affecte errno à EILSEQet retourne EILSEQ.

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

System_CAPS_ICON_important.jpg Important

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

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 Secure Template Overloads.

RoutineEn-tête requis
wcstombs_s<stdlib.h>

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

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

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

Non applicable. Pour appeler la fonction C standard, utilisez PInvoke. Pour plus d'informations, consultez Exemples d'appel de plateforme.

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

Afficher: