mbstowcs_s, _mbstowcs_s_l

Artigo
02/25/2013

Converte uma seqüência de caracteres multibyte em uma seqüência correspondente de caracteres de largura.Versões do 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

[out]pReturnValue
O número de caracteres convertidas.
[out]wcstr
Endereço do buffer para o resultante convertido cadeia de caracteres largos.
[in]sizeInWords
O tamanho da wcstr buffer em palavras.
[in]mbstr
O endereço de uma seqüência de nula finalizada caracteres multibyte.
[in]count
O número máximo de caracteres de largura para armazenar na wcstr buffer, não incluindo a 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 de retorno eerrno
wcstris NULL and sizeInWords > 0	EINVAL
mbstréNULL	EINVAL
O buffer de destino é muito pequeno para conter a seqüência convertida (a menos que count é _TRUNCATE; Consulte comentários abaixo)	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido é chamada, conforme descrito em Validação de parâmetro .Se a execução terá permissão para continuar, a função retorna um código de erro e define errno conforme indicado na tabela.

Comentários

O mbstowcs_s função converte uma seqüência de caracteres multibyte apontado pelo mbstr em caracteres de largura armazenados no buffer apontado por wcstr.A conversão continuarão para cada caractere até que uma das seguintes condições for atendida:

Um caractere nulo multibyte é encontrado
Um caractere inválido multibyte é encontrado
O número de caracteres de largura armazenados na wcstr buffer igual a count.

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

Se count é o valor especial _TRUNCATE, em seguida, mbstowcs_s converte o máximo da seqüência de caracteres como será se encaixam no buffer de destino, deixando ainda espaço para um terminador nulo.

Se mbstowcs_s com êxito converte a seqüência de origem, ele coloca o tamanho em caracteres de largura da seqüência de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (fornecido pReturnValue não NULL).Isso ocorre mesmo se a wcstr é NULL e fornece uma maneira para determinar o tamanho do buffer necessário.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

Se mbstowcs_s encontrar um caractere inválido multibyte, ele coloca 0 *pReturnValue, define o buffer de destino como uma seqüência vazia, define errno para EILSEQe retorna EILSEQ.

Se as seqüências apontado pelo mbstr e wcstr se sobrepõem, o comportamento de mbstowcs_s é indefinido.

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

mbstowcs_susa a localidade atual para qualquer comportamento depende da localidade; _mbstowcs_s_lé idêntico, exceto que ele usa a localidade passada em vez disso.Para mais informações, consulte Localidade.

No C++, usar essas funções é simplificado pela sobrecargas de modelo; as sobrecargas podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e eles automaticamente podem substituir funções mais antigas não segura com suas contrapartes mais recentes e seguras.Para mais informações, consulte Proteger Overloads de modelo.