wctomb_s, _wctomb_s_l

Artigo
06/09/2015

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

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

[saída] pRetValue
O número de bytes, ou um código que indica o resultado.
[saída] mbchar
O endereço de um caracteres multibyte.
[entrada] sizeInBytes
Tamanho do buffer mbchar.
[entrada] wchar
Um caractere largo.
[entrada] locale
A localidade a ser usada.

Valor de retorno

Zero se tiver êxito, um código de erro ou falha.

Condições de erro

mbchar	sizeInBytes	Valor de retorno	pRetValue
NULL	>0	EINVAL	não modificado
any	>INT_MAX	EINVAL	não modificado
any	muito pequeno	EINVAL	não modificado

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

Comentários

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

Se wctomb_s converte o caractere largo a um caracteres multibyte, coloca o número de bytes (que nunca é maior que MB_CUR_MAX) em caractere largo em inteiro apontado por pRetValue. Se wchar é o caractere nulo ampla de caracteres (L \ 0 '), wctomb_s preenche pRetValue com 1. Se o ponteiro mbchar de destino for NULL, wctomb_s coloca 0 em pRetValue. Se a conversão não é possível na localidade atual, wctomb_s coloca – 1 em pRetValue.

wctomb_s usa a localidade atual para as informações de localidade dependente; _wctomb_s_l é idêntico exceto que usa a localidade passada por vez. Para obter mais informações, consulte Localidade.

Requisitos

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

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

Esse programa ilustra o comportamento da função de wctomb .

// 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 );
}