sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l
Gravar dados formatados em uma cadeia de caracteres. Essas são as versões de sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l com aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.
int sprintf_s(
char *buffer,
size_t sizeOfBuffer,
const char *format [,
argument] ...
);
int _sprintf_s_l(
char *buffer,
size_t sizeOfBuffer,
const char *format,
locale_t locale [,
argument] ...
);
int swprintf_s(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format [,
argument]...
);
int _swprintf_s_l(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
locale_t locale [,
argument]…
);
template <size_t size>
int sprintf_s(
char (&buffer)[size],
const char *format [,
argument] ...
); // C++ only
template <size_t size>
int swprintf_s(
wchar_t (&buffer)[size],
const wchar_t *format [,
argument]...
); // C++ only
Parâmetros
buffer
Local de armazenamento para saídasizeOfBuffer
O número máximo de caracteres a ser armazenado.format
Cadeia de caracteres de controle de formatoargument
Argumentos opcionaislocale
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 for um ponteiro zero, sprintf_s e swprintf_s retornar -1 e definir errno como EINVAL.
sprintf_s retorna o número de bytes armazenados no buffer, sem contar o caractere nulo de terminação. swprintf_s retorna o número de caracteres amplos armazenados no buffer, sem contar o caractere amplo 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 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.
Uma diferença importante entre sprintf_s e sprintf é que sprintf_s verifica a cadeia de caracteres quanto a caracteres de formatação válidos, enquanto que sprintf verifica somente se a cadeia de caracteres de formato ou buffer são ponteiros NULL. Se a verificação falhar, o manipulador de parâmetro inválido será chamado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, a função retornará -1 e definirá errno a EINVAL.
Outra diferença importante entre sprintf_s e sprintf é que sprintf_s aceita um parâmetro de tamanho que especifica o tamanho do buffer de saída em caracteres. Se o buffer for muito pequeno para o texto que está sendo impresso, buffer será definido como uma cadeia de caracteres vazia e o manipulador de parâmetro inválido será chamado. Diferentemente do snprintf, sprintf_s garante que o buffer será finalizado como 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 caractere amplo. A detecção de erros de codificação em swprintf_s pode ser diferente da detecção em sprintf_s. 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.
No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.
Há as versões de sprintf_s que oferecem controle adicional sobre o que acontece se o buffer é muito pequeno. Para obter mais informações, consulte _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.
Mapeamentos da rotina de texto genérico
Rotina TCHAR.H |
_UNICODE & _MBCS não definido |
_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 |
<stdio.h> |
swprintf_s, _swprintf_s_l |
<stdio.h> ou <wchar.h> |
Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.
Exemplo
// 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 );
}
// 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 );
}
Equivalência do .NET Framework
Consulte também
Referência
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l