wcstombs_s, _wcstombs_s_l

Artigo
06/09/2015

Converte uma sequência de caracteres amplos a uma sequência de correspondência de caracteres de vários bytes. Uma versão de wcstombs, _wcstombs_l com aprimoramentos de segurança conforme descrito em Recursos de segurança no CRT.

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

Parâmetros

[saída] pReturnValue
O número de caracteres convertidos.
[saída] mbstr
O endereço de um buffer resultante para converter a cadeia de caracteres de vários bytes.
[in]sizeInBytes
O tamanho em bytes do buffer de mbstr .
[entrada] wcstr
Aponta para a cadeia de caracteres amplas a ser convertida.
[entrada] count
O número máximo de caracteres amplos sejam armazenados em buffer de mbstr , não incluindo o caractere 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
mbstr é NULL e sizeInBytes > 0	EINVAL
wcstr é 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

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 wcstombs_s converte uma cadeia de caracteres de caracteres amplos apontados por wcstr em caracteres multibyte armazenados em buffer apontado por mbstr. A conversão para cada caractere continuará até que uma destas condições seja atender:

Um caractere largo nulo é encontrado
Um caractere largo que não pode ser convertido for encontrado
O número de bytes armazenados em buffer de mbstr 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 wcstombs_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 wcstombs_s converte a cadeia de caracteres de origem, coloca o tamanho em bytes da cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue ( pReturnValue fornecido não for NULL). Isso ocorre mesmo se o argumento de mbstr é NULL e fornece uma maneira de determinar o tamanho de buffer necessário. Observe que se mbstr é NULL, count será ignorado.

Se wcstombs_s encontrar um caractere largo que não pode converter em um caracteres 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 wcstr e a sobreposição de mbstr , o comportamento de wcstombs_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 amplos para converter.

wcstombs_s usa a localidade atual para qualquer comportamento dependente de localidade; _wcstombs_s_l é idêntico a wcstombs 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.

Requisitos

Rotina	Cabeçalho necessário
wcstombs_s	<stdlib.h>

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

Esse programa ilustra o comportamento da função de wcstombs_s .

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t   i;
    char      *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE, 
               pWCBuffer, (size_t)BUFFER_SIZE );

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n",
     pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}