wcstombs_s, _wcstombs_s_l

Artigo
08/25/2010

Converte uma sequência de caracteres largos em uma sequência de caracteres multibyte correspondente.Uma versão do wcstombs, _wcstombs_l com aprimoramentos de segurança sistema autônomo descrito em Aprimoramentos 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

[out] pReturnValue
O número de caracteres convertida.
[out] mbstr
O endereço de um buffer para a seqüência de caractere multibyte convertido resultante.
[in]sizeInBytes
O dimensionar em bytes do mbstr buffer.
[in]wcstr
Aponta para o caractere largo seqüência de caracteres a ser convertido.
[in]count
O número máximo de bytes a ser armazenado na mbstr buffer, 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
mbstr é NULL e sizeInBytes>0	EINVAL
wcstr é 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 wcstombs_s função converte uma seqüência de caracteres largos apontada por wcstr em caracteres multibyte armazenados em buffer apontado por mbstr. A conversão continuará para cada caractere até que uma das seguintes condições seja atendida:

Encontrado um caractere de largo nulo
Um caractere largo não pode ser convertido é encontrado
O número de bytes armazenados no mbstr 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, wcstombs_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 wcstombs_s com êxito converte a seqüência de caracteres de fonte, ele coloca o dimensionar em bytes da seqüência de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (fornecido pReturnValue não é NULL). Isso ocorre mesmo se o mbstr o argumento é NULL e fornece uma maneira para determinar o dimensionar do buffer necessário. Observe que, se mbstr é NULL, count é ignorado.

If wcstombs_s encontrar um caractere largo não pode converter em um caractere de vários bytes, ele insere 0 na *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 wcstr e mbstr se sobrepõem, o comportamento do wcstombs_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 largos converter corretamente.

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

Requisitos

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

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

Exemplo

Este programa ilustra o comportamento do wcstombs_s função.

// 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);
    }
}

Convert wide-character string:    Characters converted: 14     Multibyte character: Hello, world.