wcrtomb_s

Article
06/09/2015

Convertir un caractère large dans sa représentation de caractères multioctets. Il s'agit de versions de wcrtomb avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le 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 mbchar en octets.
[in] wchar
Caractère large à convertir.
[in] mbstate
Pointeur vers un objet mbstate_t.

Valeur de retour

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

Notes

La fonction wcrtomb_s convertit un caractère large, commençant dans l'état de conversion spécifié contenu dans mbstate, depuis la valeur contenue dans wchar, dans l'adresse représentée par mbchar. La valeur pReturnValue sera le nombre d'octets convertis, mais pas plus que MB_CUR_MAX octets, ou -1 si une erreur se produit.

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

La fonction wcrtomb_s diffère de wctomb_s, _wctomb_s_l par sa capacité à redémarrer. L'état de conversion est stocké dans mbstate pour d'autres appels à la même ou a d'autres fonctions redémarrable. Les résultats sont indéfinis lorsqu'on mélange l'utilisation de fonctions redémarrable et non redémarrable. Par exemple, une application utilise wcsrlen plutôt que wcslen, si l'appel suivant à wcsrtombs_s est 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 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.

Exceptions

La fonction wcrtomb_s est multithread-safe à condition qu'aucune fonction du thread actuel n'appelle setlocale lorsque cette fonction s'exécute et que 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");
    }
}