wcrtomb_s

Artigo
08/25/2010

Converta um caractere largo em sua representação de caracteres multibyte.Uma versão do wcrtomb com aprimoramentos de segurança sistema autônomo descrito em Aprimoramentos de segurança no 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

Parâmetros

[out] pReturnValue
Retorna o número de bytes gravados ou -1 se ocorreu um erro.
[out] mbchar
Multibyte resultante é convertido em caractere.
[in]sizeOfmbchar
O dimensionar do mbchar variável em bytes.
[in]wchar
Um caractere largo para converter.
[in]mbstate
Um ponteiro para um mbstate_t objeto.

Valor de retorno

Retorna zero ou um errno valor se ocorrer um erro.

Comentários

The wcrtomb_s função converte um caractere largo, começando no estado de conversão especificada contido no mbstate, do valor contido em wchar, no endereço representado por mbchar. The pReturnValue valor será o número de bytes convertidos, mas não mais de MB_CUR_MAX bytes, ou um -1 se ocorreu um erro.

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

The wcrtomb_s função difere wctomb_s, _wctomb_s_l por sua capacidade de reinicialização. O estado de conversão é armazenado em mbstate para chamadas subseqüentes para o mesmo ou Outros funções reinicializáveis. Os resultados são indefinidos ao misturar o uso de funções nonrestartable e reinicializáveis.Por exemplo, um aplicativo utilize wcsrlen em vez de wcslen, se uma telefonar subseqüente para wcsrtombs_s foi usado em vez de wcstombs_s.

No C++, uso da função é simplificado pelo modelo sobrecargas; sobrecargas de podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de dimensionar) e eles podem substituir automaticamente funções não seguras, mais antigas, com suas contrapartes mais recentes e seguras.For more information, see Proteger overloads de modelo.

Exceções

The wcrtomb_s função é safe com vários threads sistema autônomo longo sistema autônomo nenhuma função nas chamadas de thread corrente setlocale durante a execução dessa função e o mbstate é 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.