Compartilhar via


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ída

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

  • 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 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

System::String::Format

Consulte também

Referência

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