sprintf, _sprintf_l, swprintf, _swprintf, _swprintf_l, __swprintf_l

Grave os dados formatados em uma cadeia de caracteres. Versões mais seguras de algumas dessas funções estão disponíveis; confira sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l. As versões seguras de swprintf e _swprintf_l tomar o tamanho do buffer como um parâmetro.

Sintaxe

int sprintf(
   char *buffer,
   const char *format [,
   argument] ...
);

int _sprintf_l(
   char *buffer,
   const char *format,
   _locale_t locale [,
   argument] ...
);

int swprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument]...
);

int _swprintf(
   wchar_t *buffer,
   const wchar_t *format [,
   argument]...
);

int _swprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

int __swprintf_l(
   wchar_t *buffer,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

template <size_t size>
int sprintf(
   char (&buffer)[size],
   const char *format [,
   argument] ...
); // C++ only

template <size_t size>
int _sprintf_l(
   char (&buffer)[size],
   const char *format,
   _locale_t locale [,
   argument] ...
); // C++ only

Parâmetros

buffer
Local de armazenamento para a saída

count
Número máximo de caracteres a armazenar a versão Unicode dessa função.

format
Cadeia de caracteres de controle de formato

argument
Argumentos opcionais

locale
A localidade a ser usada.

Para obter mais informações, consulte Sintaxe de especificação de formato.

Retornar valor

O número de caracteres gravados ou -1 se ocorreu um erro. Se buffer ou format for um ponteiro nulo, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno como EINVAL.

sprintf retorna o número de bytes armazenados em buffer, sem contar o caractere nulo de terminação. swprintf retorna o número de caracteres largos armazenados em buffer, sem contar o caractere largo nulo de terminação.

Comentários

A função sprintf formata e armazena uma série de caracteres e valores em buffer. Cada argument (se houver) é convertido e gerado de acordo com a especificação de formato correspondente em format. O formato consiste em caracteres comuns e tem o mesmo formato e função que o argumento format para printf. Um caractere nulo é acrescentado após o último caractere escrito. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

Importante

Usando sprintf, aqui não há maneira de limitar o número de caracteres gravados, o que significa que o código que usa sprintf é suscetível a estouros de buffer. Considere usar a função relacionada _snprintf que especifica um número máximo de caracteres a serem gravados em buffer ou use _scprintf para determinar que tamanho do buffer é necessário. Verifique também se format não é uma cadeia de caracteres definida pelo usuário.

Começando pelo Windows 10 versão 2004 (build 19041), a família de funções printf imprime números de ponto flutuante exatamente representáveis de acordo com as regras do IEEE 754 para arredondamento. Em versões anteriores do Windows, números de ponto flutuante que pudessem ser representados com exatidão e que terminassem em '5' eram sempre arredondados para cima. O IEEE 754 afirma que eles precisam arredondar para o dígito par mais próximo (também conhecido como "arredondamento bancário"). Por exemplo, ambos printf("%1.0f", 1.5) e printf("%1.0f", 2.5) devem ser arredondados para 2. Anteriormente, 1,5 seria arredondado para 2 e 2,5 para 3. Essa alteração afeta apenas números que possam ser representados com exatidão. Por exemplo, 2,35 (que, quando representado na memória, está mais próximo de 2,35000000000000008) continua arredondando para 2,4. O arredondamento feito por essas funções agora também respeita o modo de arredondamento de ponto flutuante definido por fesetround. Anteriormente, o arredondamento sempre escolhia o comportamento FE_TONEAREST. Essa alteração afeta apenas os programas criados usando o Visual Studio 2019 versão 16.2 e posteriores. Para usar o comportamento de arredondamento de ponto flutuante herdado, vincule-o a 'legacy_stdio_float_rounding.obj'.

swprintf é uma versão de caractere largo de sprintf; os argumentos de ponteiro para swprintf são cadeias de caracteres largos. A detecção de erros de codificação em swprintf pode ser diferente de sprintf. swprintfe se comportam de forma idêntica, exceto swprintf grava a saída em uma cadeia de caracteres em vez de em um destino do tipo FILE, e fwprintfswprintf requer que o parâmetro especifique o count número máximo de caracteres a serem gravados. As versões dessas funções com o sufixo _l são idênticas, com a exceção de usarem o parâmetro de localidade passado, em vez da localidade do thread atual.

Antes da assinatura para swprintf ser padronizada, uma versão fornecida em uma biblioteca de tempo de execução Microsoft C mais antiga que não usava o parâmetro de contagem de caracteres. A versão mais antiga ainda está disponível na biblioteca de tempo de execução do Microsoft C, mas foi preterida e renomeada _swprintf(). Para o código que foi escrito na assinatura mais antiga, defina _CRT_NON_CONFORMING_SWPRINTFS, que mapeia as chamadas para swprintf_swprintf. Em uma versão futura, o comportamento antigo pode ser removido, então o código deve ser alterado para usar o novo comportamento compatível.

No C++, essas funções têm sobrecargas de modelo que invocam os equivalentes mais novos e seguros dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_stprintf	sprintf	sprintf	_swprintf
_stprintf_l	_sprintf_l	_sprintf_l	__swprintf_l

Requisitos

Rotina	Cabeçalho necessário
sprintf, _sprintf_l	<stdio.h>
swprintf, _swprintf, _swprintf_l	<stdio.h> ou <wchar.h>

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

Exemplo: Usar sprintf para formatar dados

// crt_sprintf.c
// compile with: /W3
// This program uses sprintf to format various
// data and place them in the string named buffer.

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data:
   j  = sprintf( buffer,     "   String:    %s\n", s ); // C4996
   j += sprintf( buffer + j, "   Character: %c\n", c ); // C4996
   j += sprintf( buffer + j, "   Integer:   %d\n", i ); // C4996
   j += sprintf( buffer + j, "   Real:      %f\n", fp );// C4996
   // Note: sprintf is deprecated; consider using sprintf_s instead

   printf( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

Output:
   String:    computer
   Character: l
   Integer:   35
   Real:      1.732053

character count = 79

Exemplo: Tratamento de código de erro

// crt_swprintf.c
// wide character example
// also demonstrates swprintf returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}

wrote 11 characters
wrote -1 characters

Confira também

E/S de fluxo
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
Funções vprintf