mbstowcs_s, _mbstowcs_s_l

Artigo
06/09/2015

Converte uma sequência de caracteres multibyte a uma sequência de caracteres amplos correspondente. Versões de mbstowcs, _mbstowcs_l com aprimoramentos de segurança conforme descrito em Recursos de segurança no CRT.

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count 
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

[saída] pReturnValue
O número de caracteres convertidos.
[saída] wcstr
O endereço do buffer resultante para converter a cadeia de caracteres amplas.
[entrada] sizeInWords
O tamanho do buffer de wcstr no word.
[in]mbstr
O endereço de uma sequência de zero terminou caracteres multibyte.
[entrada] count
O número máximo de caracteres amplos a armazenar em buffer de wcstr , não incluindo o terminador nulo, ou _TRUNCATE.
[entrada] locale
A localidade a ser usada.

Valor de retorno

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

Condição de erro	Valor de retorno e errno
wcstr é NULL e sizeInWords > 0	EINVAL
mbstr é NULL	EINVAL
O buffer de destino for muito pequeno conter a cadeia de caracteres convertida (a menos que count é _TRUNCATE; consulte os comentários abaixo)	ERANGE
wcstr não é NULL e == 0 de sizeInWords	EINVAL

Se alguma dessas condições ocorrer, a exceção inválido do parâmetro é chamada conforme descrito em Validação do parâmetro . Se a execução for permitida continuar, a função retornará um código de erro e define errno conforme indicado na tabela.

Comentários

A função de mbstowcs_s converte uma cadeia de caracteres de caracteres multibyte apontados por mbstr em caracteres amplos armazenados em buffer apontado por wcstr. A conversão para cada caractere continuará até que uma destas condições seja atender:

Um caractere nulo é encontrado multibyte
Um caractere inválido multibyte for encontrado
O número de caracteres amplos armazenados no buffer de wcstr igual count.

A cadeia de caracteres de destino tiver terminação sempre (até mesmo no caso de um erro).

Se count é o valor especial _TRUNCATE, então mbstowcs_s converte o máximo possível da cadeia de caracteres como caiba no buffer de destino, enquanto ainda deixar de espaço para um terminador nulo.

Se mbstowcs_s converte a cadeia de caracteres de origem, coloca o tamanho em caracteres amplos de cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue ( pReturnValue fornecido não for NULL). Isso ocorre mesmo se o argumento de wcstr é NULL e fornece uma maneira de determinar o tamanho de buffer necessário. Observe que se wcstr é NULL, count é ignorado, e sizeInWords deve ser 0.

Se mbstowcs_s encontrar um caractere inválido multibyte, o coloca 0 em *pReturnValue, define o buffer de destino em uma cadeia de caracteres vazia, define errno a EILSEQ, e retorna EILSEQ.

Se as sequências apontadas por mbstr e a sobreposição de wcstr , o comportamento de mbstowcs_s são indefinidas.

Observação de segurança
Certifique-se de que wcstr e mbstr não se sobrepõem, e que count reflete corretamente o número de caracteres multibyte para converter.

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

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.