wcrtomb_s

Converta um caractere largo em sua representação de caracteres multibyte. Uma versão de wcrtomb com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

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

Parâmetros

pReturnValue
Retorna o número de bytes gravados ou –1 em caso de erro.

mbchar
O caractere multibyte convertido resultante.

sizeOfmbchar
O tamanho da variável mbchar em bytes.

wchar
Um caractere largo a ser convertido.

mbstate
Um ponteiro para um objeto mbstate_t.

Valor retornado

Retorna zero ou um valor errno em caso de erro.

Comentários

A função wcrtomb_s converte um caractere largo que começa no estado da conversão especificado contido em mbstate, com base no valor contido em wchar, no endereço representado por mbchar. O valor pReturnValue será o número de bytes convertidos, mas não mais de MB_CUR_MAX bytes ou –1 em caso de erro.

Se mbstate for nulo, o estado da conversão mbstate_t interno será usado. Se o caractere contido em wchar não tiver um caractere multibyte correspondente, o valor de pReturnValue será -1 e a função retornará o errno valor de EILSEQ.

A wcrtomb_s função difere de , _wctomb_s_l por sua capacidade de wctomb_sreinicialização. O estado da conversão é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo usaria wcsrlen em vez de wcslen se uma chamada subsequente a wcsrtombs_s fosse usada em vez de wcstombs_s.

Em C++, o uso dessa função é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Exceções

A função wcrtomb_s será multithread-safe contanto que nenhuma função no thread atual chame setlocale enquanto essa função estiver em execução e o mbstate for nulo.

Exemplo

// 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.

Requisitos

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
mbsinit