sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l

Artigo
07/08/2015

Gravar dados formatados em uma cadeia de caracteres. Versões mais seguras de algumas dessas funções estão disponíveis; consulte sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l. As versões seguras de swprintf e de _swprintf_l não têm um parâmetro count .

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_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
template <size_t size>
int swprintf(
   wchar_t (&buffer)[size],
   const wchar_t *format [,
   argument]...
); // C++ only
template <size_t size>
int _swprintf_l(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
); // C++ only

Parâmetros

buffer
Local de armazenamento para saída
count
Número máximo de caracteres para 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 Especificações de formato.

Valor de retorno

O número de caracteres gravados, ou – 1 se ocorrer um erro. Se buffer ou format são um ponteiro nulo, o parâmetro de manipulador inválido é invocado, como descrito em Validação do parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno a EINVAL.

sprintf retorna o número de bytes armazenados no buffer, sem contar o caractere nulo de terminação. swprintfretorna o número de caracteres amplos armazenados no buffer, sem contar o caractere amplo 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 do 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.

Observação de segurança
Usando o sprintf, não há nenhuma maneira de limitar o número de caracteres gravados, o que significa que o código que usa o 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 usar _scprintf para determinar o tamanho necessário para um buffer.Além disso, verifique se format não é uma cadeia de caracteres definida pelo usuário.

Usando o sprintf, não há nenhuma maneira de limitar o número de caracteres gravados, o que significa que o código que usa o 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 usar _scprintf para determinar o tamanho necessário para um buffer.Além disso, verifique se format não é uma cadeia de caracteres definida pelo usuário.

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

swprintf estão de acordo com o Padrão ISO C, que exige o segundo parâmetro, count, do tipo size_t. Para forçar o comportamento diferente do padrão antigo, defina _CRT_NON_CONFORMING_SWPRINTFS. Em uma versão futura, como o comportamento anterior pode ser removido, o código deve ser alterado para usar o novo comportamento adequado.

No C++, essas funções têm as sobrecargas de modelo que invocam as correspondentes seguras mais recentes dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_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_l	<stdio.h> ou <wchar.h>

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

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

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