wcrtomb_s
Converter 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.
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
[saída] pReturnValue
Retorna o número de bytes gravados ou -1 se um erro ocorreu.[saída] mbchar
O caractere convertido multibyte resultante.[entrada] sizeOfmbchar
O tamanho da variável de mbchar em bytes.[entrada] wchar
Um caractere largo a ser convertida.[entrada] mbstate
Um ponteiro para um objeto mbstate_t.
Valor de retorno
Retorna zero ou um valor de errno se ocorrer um erro.
Comentários
A função de wcrtomb_s converte um caractere largo, começando no estado especificado de conversão contido em mbstate, do valor contido em wchar, no endereço representado por mbchar. O valor de pReturnValue será o número de bytes convertidos, mas não mais do que bytes de MB_CUR_MAX , ou um -1 se um erro ocorreu.
Se mbstate for nulo, o estado interno da conversão de mbstate_t será usado. Se o caractere contido em wchar não tiver um caractere correspondente de multibyte, o valor de pReturnValue será -1 e a função retornará o valor de errno de EILSEQ.
A função de wcrtomb_s difere de wctomb_s, _wctomb_s_l por seu restartability. O estado da conversão é armazenado em mbstate para chamadas subsequentes à mesma ou a outras funções restartable. Os resultados são definidos ao misturar o uso de funções restartable e nonrestartable. Por exemplo, um aplicativo use wcsrlen em vez de wcslen, se uma chamada subsequente a wcsrtombs_s foi usado em vez de wcstombs_s.
Em C++, usar essa função é simplificada por sobrecargas do modelo; as sobrecargas pode deduzir o comprimento do buffer automaticamente (o que elimina a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente mais antigos, funções de não seguras com suas contrapartes mais novos, seguros. Para obter mais informações, consulte Sobrecargas de modelo seguras.
Exceções
A função de wcrtomb_s é seguro multi-threaded desde que nenhuma função no thread atual chama setlocale quando essa função executar e 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");
}
}
Equivalência do .NET Framework
Não aplicável. Para chamar a função padrão de C, use PInvoke. Para obter mais informações, consulte Exemplos de chamadas de plataformas.
Requisitos
Rotina |
Cabeçalho necessário |
---|---|
wcrtomb_s |
<wchar.h> |