wcstombs_s, _wcstombs_s_l

Converte uma sequência de caracteres largos numa sequência correspondente de caracteres de vários bytes. Uma versão de wcstombs, _wcstombs_l com melhorias de segurança descritas em Funcionalidades de Segurança no CRT.

Sintaxe

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

pReturnValue
O tamanho em bytes da cadeia convertida, incluindo o terminador nulo.

mbstr
O endereço de um buffer para a cadeia de caracteres multibyte convertida resultante.

sizeInBytes
O tamanho em bytes do mbstr buffer.

wcstr
Aponta para a cadeia larga de caracteres a converter.

count
O número máximo de bytes a armazenar no mbstr buffer, excluindo o carácter nulo de terminação, ou _TRUNCATE.

locale
A localidade a ser usada.

Valor de retorno

Zero se for bem-sucedido, código de erro em caso de falha.

Se alguma destas condições ocorrer, a exceção de parâmetro inválida é invocada conforme descrito na validação de parâmetros. Se a execução for permitida continuar, a função devolve um código de erro e define errno conforme indicado na tabela.

Observações

A wcstombs_s função converte uma cadeia de caracteres largos apontados para por wcstr em caracteres multibyte armazenados no buffer apontado por mbstr. A conversão continuará para cada personagem até que uma destas condições seja cumprida:

• Encontra-se um carácter null wide

• Encontra-se um carácter amplo que não pode ser convertido

• O número de bytes armazenados no mbstr buffer é countigual a .

A cadeia de destino é sempre terminada por null (mesmo que haja um erro).

Se count for o valor _TRUNCATEespecial , então wcstombs_s converte tanto da cadeia quanto caber no buffer de destino, deixando ainda espaço para um terminador nulo. Se a cadeia for truncada, o valor de retorno é STRUNCATE, e a conversão é considerada bem-sucedida.

Se wcstombs_s converter com sucesso a cadeia de origem, coloca o tamanho em bytes da cadeia convertida, incluindo o terminador nulo, em *pReturnValue (desde que pReturnValue não NULLseja ). O tamanho é calculado mesmo que o argumento mbstr seja NULL; fornece uma forma de determinar o tamanho do buffer necessário. Se mbstr for NULL, count é ignorado.

Se wcstombs_s encontrar um carácter amplo que não consegue converter para um carácter multibyte, coloca 0 em *ReturnValue, define o buffer de destino para uma string vazia, define errno para EILSEQ, e retorna EILSEQ.

Se as sequências apontarem para por wcstr e mbstr se sobreporem, o comportamento de wcstombs_s é indefinido.

wcstombs_s usa a localização atual para qualquer comportamento dependente da localização; _wcstombs_s_l é idêntico a wcstombs exceto que usa o local passado em vez disso. Para obter mais informações, consulte Localidade.

Em C++, a utilização destas funções é simplificada por sobrecargas de templates; As sobrecargas podem inferir automaticamente o comprimento do buffer (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções antigas e não seguras pelas suas contrapartes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguro.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Requisitos

Para obter mais informações sobre compatibilidade, consulte Compatibilidade.

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 );
    const 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 - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

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

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

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

Consulte também

Conversão de dados
Locale
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte