wctomb_s, _wctomb_s_l

Converte um caractere largo no caractere multibyte correspondente. Uma versão do , com aprimoramentos de segurança, conforme descrito em Recursos de wctombsegurança na CRT. _wctomb_l

Sintaxe

errno_t wctomb_s(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar
);
errno_t _wctomb_s_l(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar,
   _locale_t locale
);

Parâmetros

pRetValue
O número de bytes ou um código que indica o resultado.

mbchar
O endereço de um caractere multibyte.

sizeInBytes
O tamanho do buffer mbchar.

wchar
O caractere largo a ser convertido.

locale
A localidade a ser usada.

Retornar valor

Zero se for bem-sucedido ou um código de erro em caso de falha.

Condições de erro

mbchar	sizeInBytes	Retornar valor	pRetValue
NULL	>0	EINVAL	não modificado
qualquer	>INT_MAX	EINVAL	não modificado
qualquer	muito pequeno	EINVAL	não modificado

Se qualquer uma das condições de erro acima ocorrer, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, wctomb retornará EINVAL e definirá errno como EINVAL.

O valor de retorno indica que o valor EILSEQ passado pelo parâmetro wchar não é um caractere largo válido.

Comentários

A função wctomb_s converte seu argumento wchar no caractere multibyte correspondente e armazena o resultado em mbchar. Você pode chamar a função de qualquer ponto, em qualquer programa.

Se wctomb_s converter o caractere largo em um caractere multibyte, ele colocará o número de bytes (que nunca será maior que MB_CUR_MAX) no caractere largo para o inteiro apontado por pRetValue. Se wchar for o caractere nulo de caractere largo (L'\0'), wctomb_s preencherá pRetValue com 1. Se o ponteiro mbchar de destino for NULL, wctomb_s colocará 0 em pRetValue. Se a conversão não for possível na localidade atual, wctomb_s coloque -1 em pRetValue.

wctomb_s usa a localidade atual de qualquer informação dependente da localidade; _wctomb_s_l é idêntico, exceto pelo fato de que ele usa a localidade passada. Para obter mais informações, consulte Localidade.

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

Requisitos

Rotina	Cabeçalho necessário
wctomb_s	<stdlib.h>
_wctomb_s_l	<stdlib.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Este programa ilustra o comportamento da função wctomb_s.

// crt_wctomb_s.cpp
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    int i;
    wchar_t wc = L'a';
    char *pmb = (char *)malloc( MB_CUR_MAX );

    printf_s( "Convert a wide character:\n" );
    wctomb_s( &i, pmb, MB_CUR_MAX, wc );
    printf_s( "   Characters converted: %u\n", i );
    printf_s( "   Multibyte character: %.1s\n\n", pmb );
}

Convert a wide character:
   Characters converted: 1
   Multibyte character: a

Confira também

Conversão de dados
Localidade
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
WideCharToMultiByte