wcrtomb_s

Article
03/04/2013

Convertissez un caractère élargi en sa représentation de caractères multioctets.Une version de wcrtomb avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

Paramètres

[out] pReturnValue
Retourne le nombre d'octets écrits ou -1 si une erreur s'est produite.
[out] mbchar
Le caractère converti multioctets résultant.
[in] sizeOfmbchar
la taille de la variable d' mbchar en octets.
[in] wchar
Un caractère élargi à convertir.
[in] mbstate
Un pointeur vers un objet d' mbstate_t .

Valeur de retour

Retourne zéro ou une valeur d' errno si une erreur se produit.

Notes

La fonction d' wcrtomb_s convertit un caractère élargi, en commençant dans le rapport de conversion spécifié contenu dans mbstate, la valeur contenue dans wchar, dans l'adresse représentée par mbchar.La valeur d' pReturnValue ne sera le nombre d'octets convertis, mais pas plus que les octets d' MB_CUR_MAX , ou un -1 si une erreur s'est produite.

Si mbstate est null, le rapport de conversion interne d' mbstate_t est utilisé.Si le caractère contenu dans wchar n'a pas un caractère multioctets correspondant, la valeur d' pReturnValue est -1 et la fonction retourne la valeur d' errno d' EILSEQ.

la fonction d' wcrtomb_s diffère de wctomb_s, _wctomb_s_l par sa capacité à redémarrer.Le rapport de conversion est stocké dans mbstate pour les appels suivants à la même transparence ou à d'autres fonctions restartable.Les résultats sont indéfinis en combinant l'utilisation des fonctions restartable et nonrestartable.Par exemple, une application utilise wcsrlen plutôt qu' wcslen, si un appel suivant à wcsrtombs_s étaient utilisés au lieu d' wcstombs_s.

En C++, grâce à cette fonction 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.

Exceptions

La fonction d' wcrtomb_s est multithread-safe tant qu'aucune fonction dans le thread actuel n'appelle setlocale bien que cette fonction s'exécute et mbstate est null.

Exemple

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}