wcstombs_s, _wcstombs_s_l

Artigo
02/25/2013

Converte uma seqüência de caracteres de largura para uma seqüência de correspondente de caracteres multibyte.Uma versão do 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

[out]pReturnValue
O número de caracteres convertidas.
[out]mbstr
O endereço de um buffer para a seqüência de caracteres multibyte convertido resultante.
[in]sizeInBytes
O tamanho em bytes da mbstr buffer.
[in]wcstr
Aponta para a seqüência de caracteres de largura a ser convertido.
[in]count
O número máximo de caracteres extensos seja armazenado na mbstr buffer, não incluindo o caractere nulo de terminação, 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
mbstris NULL and sizeInBytes > 0	EINVAL
wcstréNULL	EINVAL
O buffer de destino é muito pequeno para conter a seqüência convertida (a menos que count é _TRUNCATE; Consulte os comentários abaixo)	ERANGE

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido é invocada, 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 wcstombs_s função converte uma seqüência de caracteres de largura apontada por wcstr em caracteres multibyte armazenados no buffer apontado por mbstr.A conversão continuará para cada caractere, até que uma das seguintes condições seja atendida:

Um caractere de largo nulo é encontrado.
Um caractere longo que não pode ser convertido é encontrado.
O número de bytes armazenados na mbstr de buffer é igual a count.

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

Se count é o valor especial _TRUNCATE, em seguida, wcstombs_s converte o máximo da seqüência de caracteres como irá cabe no buffer de destino, enquanto ainda deixa espaço para um terminador nulo.

Se wcstombs_s com êxito, converte a seqüência de origem, ele coloca o tamanho em bytes da seqüência de caracteres convertida, incluindo o terminador null, em *pReturnValue (fornecidos pReturnValue não é NULL).Isso ocorre mesmo se o mbstr argumento é NULL e fornece uma maneira para determinar o tamanho do buffer necessário.Note that if mbstr is NULL, count is ignored.

Se wcstombs_s encontra um caractere largo, ele não é possível converter um caractere multibyte, ele coloca 0 em *pReturnValue, define o buffer de destino como uma seqüência vazia, define errno para EILSEQe retorna EILSEQ.

Se as seqüências apontada por wcstr e mbstr se sobrepõem, o comportamento de wcstombs_s é indefinido.

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

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

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

Requisitos

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

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

Exemplo

Este programa ilustra o comportamento da 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);
    }
}