wcsrtombs_s

Converte uma cadeia de caracteres largos em sua representação de cadeia de caracteres multibyte. Uma versão de wcsrtombs com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parâmetros

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

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

sizeInBytes
O tamanho em bytes do buffer mbstr.

wcstr
Aponta para a cadeia de caracteres largos a ser convertida.

count
O número máximo de bytes a serem armazenados no mbstr buffer ou _TRUNCATE.

mbstate
Um ponteiro para um objeto do estado da conversão mbstate_t.

Retornar valor

Zero se for bem-sucedido ou 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 cadeia de caracteres convertida (a menos que count seja _TRUNCATE; consulte Comentários abaixo)	ERANGE

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido será invocada conforme descrito em Validação de parâmetro . Se a execução puder continuar, a função retornará um código de erro e definirá errno conforme indicado na tabela.

Comentários

A função wcsrtombs_s converte uma cadeia de caracteres largos apontada por wcstr em caracteres multibyte armazenados no buffer apontado por mbstr usando o estado da conversão contido em mbstate. A conversão continuará para cada caractere até que uma das seguintes condições seja atendida:

• Um caractere largo nulo é encontrado

• Um caractere largo que não pode ser convertido é encontrado

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

A cadeia de caracteres de destino é sempre terminada em nulo (mesmo se houver um erro).

Se count for o valor especial _TRUNCATE, wcsrtombs_s converterá o máximo da cadeia de caracteres que caberá no buffer de destino ainda deixando espaço para um terminador nulo.

Se wcsrtombs_s converter com êxito a cadeia de caracteres de origem, ela colocará o tamanho em bytes da cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (desde pReturnValue que não NULLseja ). O tamanho é calculado mesmo se o argumento for NULL, ele fornece uma maneira de determinar o mbstr tamanho do buffer necessário. Se mbstr for NULL, count será ignorado.

Se wcsrtombs_s encontrar um caractere largo que não possa ser convertido em um caractere multibyte, ele colocará -1 no *pReturnValue, definirá o buffer de destino como uma cadeia de caracteres vazia, definirá errno como EILSEQe retornará EILSEQ.

Se as sequências apontadas por wcstr e por mbstr se sobrepuserem, o comportamento de wcsrtombs_s será indefinido. wcsrtombs_s é afetado pela categoria LC_TYPE da localidade atual.

Importante

Verifique se wcstr e mbstr não se sobrepõem e se count reflete corretamente o número de caracteres largos a ser convertido.

A wcsrtombs_s função difere de , _wcstombs_s_l por sua capacidade de wcstombs_sreinicialização. O estado da conversão é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo usaria wcsrlen em vez de wcslen se uma chamada subsequente a wcsrtombs_s fosse usada em vez de wcstombs_s.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

Exceções

A função wcsrtombs_s será multithread-safe contanto que nenhuma função no thread atual chame setlocale enquanto essa função estiver em execução e o mbstate for nulo.

Exemplo

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Requisitos

Rotina	Cabeçalho necessário
wcsrtombs_s	<wchar.h>

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit