mbstowcs_s, _mbstowcs_s_l

Artigo
08/25/2010

Converte uma sequência de caracteres multibyte em uma sequência correspondente de caracteres largos.Versões de mbstowcs, _mbstowcs_l com aprimoramentos de segurança sistema autônomo descrito em Aprimoramentos 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

[out] pReturnValue
O número de caracteres convertida.
[out] wcstr
Endereço do buffer para a seqüência de caractere largos convertido resultante.
[in]sizeInWords
O dimensionar do wcstr buffer em palavras.
[in]mbstr
O endereço de uma sequência de nulo finalizada caracteres multibyte.
[in]count
O número máximo de caracteres largos para armazenar o wcstr buffer, não incluindo terminação nula, ou _TRUNCATE.
[in]locale
A localidade para usar.

Valor de retorno

Zero se for bem-sucedido, 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 seqüência de caracteres convertida (a menos que count é _TRUNCATEConsulte os comentários abaixo)	ERANGE

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido é invocada sistema autônomo descrito em Validação de parâmetro . Se a execução for permitida para continuar, a função retorna um código de erro e define errno sistema autônomo indicado na tabela.

Comentários

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

Encontrado um caractere nulo multibyte
Encontrado um caractere inválido multibyte
O número de caracteres larga armazenados no wcstr buffer é igual a count.

A seqüência de caracteres de destino sempre é terminada por caractere nulo (até mesmo no caso de erro).

If count é o valor especial _TRUNCATE, em seguida, mbstowcs_s Converte sistema autônomo da seqüência de caracteres sistema autônomo couberem no buffer de destino, enquanto ainda deixa espaço para um terminador nulo.

If mbstowcs_s Converte a seqüência de caracteres de fonte, com êxito colocará o dimensionar em caracteres largos da seqüência de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (fornecido pReturnValue não é NULL). Isso ocorre mesmo se o wcstr o argumento é NULL e fornece uma maneira para determinar o dimensionar do buffer necessário. Observe que, se wcstr é NULL, count é ignorado, e sizeInWords deve ser 0.

If mbstowcs_s encontrar um caractere inválido multibyte, colocará 0 em *pReturnValue, define o buffer de destino como uma seqüência de caracteres vazia, conjuntos errno para EILSEQe retorna EILSEQ.

Se as seqüências apontada por mbstr e wcstr se sobrepõem, o comportamento do mbstowcs_s não está definida.

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

mbstowcs_s usa a localidade corrente para qualquer comportamento dependente de localidade; _mbstowcs_s_l é idêntico, exceto pelo fato de que ele usa a localidade do passado em vez disso. For more information, see Localidade.

No C++, usando essas funções é simplificado pelo modelo sobrecargas; sobrecargas de podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de dimensionar) e eles podem substituir automaticamente funções não seguras, mais antigas, com suas contrapartes mais recentes e seguras.For more information, see Proteger overloads de modelo.