wcrtomb_s

Convertit un caractère large dans sa représentation de caractère multioctet. Version des améliorations de wcrtomb sécurité décrites dans les fonctionnalités de sécurité du CRT.

Syntaxe

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

pReturnValue
Retourne le nombre de caractères écrits ou -1 si une erreur s’est produite.

mbchar
Résultat de la conversion du caractère multioctet.

sizeOfmbchar
Taille de la variable mbchar en octets.

wchar
Caractère large à convertir.

mbstate
Pointeur vers un objet mbstate_t .

Valeur retournée

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

Notes

La fonction wcrtomb_s convertit un caractère large, en commençant dans l’état de conversion spécifié dans mbstate, à partir de la valeur contenue dans wchar, en adresse représentée par mbchar. La valeur pReturnValue correspond au nombre d’octets convertis, mais pas plus de MB_CUR_MAX octets, ou -1 si une erreur s’est produite.

Si mbstate a la valeur null, l’état de conversion mbstate_t interne est utilisé. Si le caractère contenu dans wchar n’a pas de caractère multioctet correspondant, la valeur de pReturnValue -1 et la fonction retourne la errno valeur de EILSEQ.

La wcrtomb_s fonction diffère de , _wctomb_s_l par wctomb_ssa capacité de redémarrage. L'état de la conversion est stocké dans mbstate pour les appels suivants à la même ou à d'autres fonctions redémarrables. Les résultats ne sont pas définis quand l'utilisation de fonctions redémarrables est combinée avec l'utilisation de fonctions non redémarrables. Par exemple, une application utiliserait wcsrlen plutôt que wcslen si un appel ultérieur à wcsrtombs_s était utilisé à la place de wcstombs_s.

En C++, l’utilisation de cette fonction 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 de taille) et peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalents plus récents et sécurisés. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Exceptions

La fonction wcrtomb_s est multithread-safe tant qu’aucune fonction du thread actif n’appelle setlocale pendant l’exécution de cette fonction et que mbstate a la valeur 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");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

Spécifications

Voir aussi

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
mbsinit