mbstowcs_s, _mbstowcs_s_l

Converte uma sequência de caracteres multibyte em uma sequência de caracteres largos correspondente. Versões do , com aprimoramentos de segurança, conforme descrito em Recursos de mbstowcssegurança na CRT. _mbstowcs_l

Sintaxe

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

pReturnValue
O número de caracteres convertidos.

wcstr
Endereço do buffer para a cadeia de caracteres largos convertida resultante.

sizeInWords
O tamanho do buffer wcstr em palavras.

mbstr
O endereço de uma sequência de caracteres multibyte terminadas por nulo.

count
O número máximo de caracteres largos a serem armazenados no buffer wcstr, não incluindo o caractere nulo de terminação ou _TRUNCATE.

locale
A localidade a ser usada.

Retornar valor

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

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

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido será invocada conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará um código de erro e definirá errno conforme indicado na tabela.

Comentários

A função mbstowcs_s converte uma cadeia de caracteres multibyte apontada por mbstr em caracteres largos armazenados no buffer apontado por wcstr. A conversão continuará para cada caractere até que uma das seguintes condições seja atendida:

• Um caractere nulo multibyte é encontrado

• Um caractere multibyte inválido é encontrado

• O número de caracteres largos armazenados no buffer wcstr é igual a count.

A cadeia de caracteres de destino é sempre terminada em nulo (mesmo se houver um erro).

Se count for o valor especial _TRUNCATE, mbstowcs_s converterá o máximo da cadeia de caracteres que caberá no buffer de destino ainda deixando espaço para um terminador nulo.

Se mbstowcs_s converter com êxito a cadeia de caracteres de origem, ela colocará o tamanho em caracteres largos da cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (desde pReturnValue que não NULLseja ). O tamanho é calculado mesmo se o argumento for NULL, e fornece uma maneira de determinar o wcstr tamanho do buffer necessário. Se wcstr é , count é NULLignorado e sizeInWords deve ser 0.

Se mbstowcs_s encontrar um caractere multibyte inválido, ele colocará 0 em *pReturnValue, definirá o buffer de destino como uma cadeia de caracteres vazia, definirá errno como EILSEQe retornará EILSEQ.

Se as sequências apontadas por mbstr e por wcstr se sobrepuserem, o comportamento de mbstowcs_s será indefinido.

Importante

Verifique se wcstr e mbstr não se sobrepõem e se count reflete corretamente o número de caracteres multibyte a ser convertido.

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

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

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

Confira também

Conversão de dados
Localidade
MultiByteToWideChar
Interpretação de sequências de caracteres multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l