sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Grave os dados formatados em uma cadeia de caracteres. Essas funções são versões do , , , , com aprimoramentos de segurança, _sprintf_lswprintfconforme descrito em Recursos de sprintfsegurança na CRT.__swprintf_l_swprintf_l

Sintaxe

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   ...
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   _locale_t locale,
   ...
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   ...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   _locale_t locale,
   ...
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format,
   ...
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   ...
); // C++ only

Parâmetros

buffer
Local de armazenamento para a saída

sizeOfBuffer
O número máximo de caracteres a ser armazenado.

format
Cadeia de caracteres de controle de formato

...
Argumentos opcionais para serem formatados

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 é um ponteiro nulo, sprintf_s e swprintf_s retornam -1 e definem errno para EINVAL.

sprintf_s retorna o número de bytes armazenados em buffer, sem contar o caractere nulo de terminação. swprintf_s 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_s 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.

Uma diferença principal entre sprintf_s e sprintf é que sprintf_s verifica a cadeia de caracteres de formato para caracteres de formatação válidos, enquanto sprintf apenas verifica se a cadeia de caracteres de formato ou buffer são ponteiros NULL. Se uma verificação falhar, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará um valor -1 e definirá errno como EINVAL.

A outra diferença principal entre sprintf_s e sprintf é que sprintf_s assume um parâmetro de comprimento que especifica o tamanho do buffer de saída em caracteres. Se o buffer for muito pequeno para o texto formatado, incluindo o nulo de terminação, o buffer será definido como uma cadeia de caracteres vazia colocando-se um caractere nulo em buffer[0], então o manipulador de parâmetro inválido será invocado. Ao contrário de _snprintf, sprintf_s assegura que o buffer será terminado em caractere nulo, a menos que o tamanho do buffer seja zero.

swprintf_s é uma versão de caractere largo de sprintf_s; os argumentos de ponteiro para swprintf_s são cadeias de caracteres largos. A detecção de erros de codificação em pode diferir da detecção em swprintf_ssprintf_s. 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.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir automaticamente o tamanho do buffer, o que elimina a necessidade de especificar um argumento de tamanho. E eles podem substituir automaticamente funções mais antigas e não seguras por contrapartes mais novas e mais seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Existem versões sprintf_s que oferecem mais controle sobre o que acontece se o buffer for muito pequeno. Para mais informações, confira _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

Importante

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'.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Requisitos

Rotina	Cabeçalho necessário
sprintf_s, _sprintf_s_l	C: <stdio.h> C++: <cstdio> ou <stdio.h>
swprintf_s, _swprintf_s_l	C: <stdio.h> ou <wchar.h> C++: <cstdio>, <cwchar>, <stdio.h> ou <wchar.h>

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

Exemplo: Usar sprintf_s para formatar dados

// crt_sprintf_s.c
// This program uses sprintf_s 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_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "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_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s 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
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
Funções vprintf