`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`

Artigo
10/12/2023

Grava dados formatados em uma cadeia de caracteres. Essas funções são versões do , , , _snprintf_snprintf_l, _snwprintfcom_snwprintf_laprimoramentos de segurança descritos em Recursos de snprintfsegurança na CRT.

Sintaxe

int _snprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
);

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

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

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

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

Parâmetros

buffer
Local de armazenamento para a saída.

sizeOfBuffer
O tamanho do local de armazenamento para a saída. Tamanho em bytes para as funções que tomam , e palavras para aquelas que tomam charwchar_t.

count
O número máximo de caracteres a serem gravados. Para as funções que levam wchar_t, é o número máximo de caracteres largos para escrever. Ou _TRUNCATE.

format
Cadeia de caracteres de controle de formato.

argument
Argumentos opcionais.

locale
A localidade a ser usada.

Retornar valor

O número de caracteres escritos, não incluindo o término NULL. Um valor negativo será retornado se ocorrer um erro de saída. Consulte Resumo do comportamento para obter detalhes.

Comentários

A _snprintf_s função formata e armazena count ou menos caracteres em buffer e acrescenta um terminando NULL. Cada argumento (se houver) é convertido e gerado de acordo com a especificação de formato correspondente em format. A formatação é consistente com a printf família de funções, consulte Sintaxe de especificação de formato: printf e wprintf funções. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

Resumo do comportamento

Para a tabela a seguir:

-Seja len o tamanho dos dados formatados. Se a função usa um char buffer, o tamanho é em bytes. Se a função usar um wchar_t buffer, o tamanho especificará o número de palavras de 16 bits.

Caracteres referem-se a caracteres para funções que usam um buffer e a charwchar_t caracteres para funções que usam um charwchar_t buffer.
Para obter mais informações sobre o manipulador de parâmetros inválidos, consulte Validação de parâmetro.

Condição	Comportamento	Retornar valor	`errno`	Invoca um manipulador de parâmetro inválido
Sucesso	Grava os caracteres no buffer usando a cadeia de caracteres de formato especificada.	O número de caracteres escritos, não incluindo o término `NULL`.	N/D	Não
Erro de codificação durante a formatação	Se o processamento do especificador `s`de cadeia de caracteres , ou `Z`, `S`o processamento de especificação de formato for interrompido.	-1	`EILSEQ` (42)	Não
Erro de codificação durante a formatação	Se o especificador `c` de caracteres de processamento ou `C`, o caractere inválido será ignorado. O número de caracteres gravados não é incrementado para o caractere ignorado, nem os dados são gravados para ele. O processamento da especificação de formato continua depois de ignorar o especificador com o erro de codificação.	O número de caracteres escritos, não incluindo o término `NULL`.	`EILSEQ` (42)	Não
`buffer == NULL` e `sizeOfBuffer == 0` e `count == 0`	Nenhum dado é gravado.	0	N/D	Não
`buffer == NULL`e ou `sizeOfBuffer != 0count != 0`	Se a execução continuar após a execução do manipulador de parâmetros inválido, definirá `errno` e retornará um valor negativo.	-1	`EINVAL` (22)	Sim
`buffer != NULL` e `sizeOfBuffer == 0`	Nenhum dado é gravado.	-1	`EINVAL` (22)	Sim
`count == 0`	A `NULL` é colocado no início do buffer.	-1	N/D	Não
`count < 0`	Não seguro: o valor é tratado como não assinado, provavelmente criando um valor grande que resulta na substituição da memória que segue o buffer.	O número de caracteres escritos, não incluindo o término `NULL`.	N/D	Não
`count < sizeOfBuffer` e `len <= count`	Todos os dados são gravados e uma rescisão `NULL` é anexada.	O número de caracteres gravados.	N/D	Não
`count < sizeOfBuffer` e `len > count`	Os primeiros `count` caracteres são escritos e um término `NULL` é acrescentado.	-1	N/D	Não
`count >= sizeOfBuffer` e `len < sizeOfBuffer`	Todos os dados são gravados com um arquivo `NULL`.	O número de caracteres gravados.	N/D	Não
`count >= sizeOfBuffer` e `len >= sizeOfBuffer` e `count != _TRUNCATE`	Se a execução continuar após a execução do manipulador de parâmetros inválido, define `errno`, define `buffer[0] == NULL`e retorna um valor negativo.	-1	`ERANGE` (34)	Sim
`count == _TRUNCATE` e `len >= sizeOfBuffer`	Grava o máximo de sequência de caracteres que couber e `buffer` um terminando `NULL`.	-1	N/D	Não
`count == _TRUNCATE` e `len < sizeOfBuffer`	Grava a cadeia de caracteres inteira em `buffer` com um arquivo `NULL`.	Número de caracteres escritos, não incluindo o terminando `NULL`.	N/D	Não
`format == NULL`	Nenhum dado é gravado. Se a execução continuar após a execução do manipulador de parâmetros inválido, definirá `errno` e retornará um valor negativo.	-1	`EINVAL` (22)	Sim

Para obter informações sobre esses e outros códigos de erro, confira _doserrno, errno, _sys_errlist e _sys_nerr.

Importante

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

_snwprintf_s é uma versão de caractere largo de _snprintf_s; os argumentos de ponteiro para _snwprintf_s são cadeias de caracteres largos. A detecção de erros de codificação em _snwprintf_s pode ser diferente da detecção em _snprintf_s. _snwprintf_s, assim como swprintf_s, grava o resultado em uma cadeia de caracteres em vez de em um destino do tipo FILE.

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.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. 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
`_sntprintf_s`	`_snprintf_s`	`_snprintf_s`	`_snwprintf_s`
`_sntprintf_s_l`	`_snprintf_s_l`	`_snprintf_s_l`	`_snwprintf_s_l`

Requisitos

Rotina	Cabeçalho necessário
`_snprintf_s`, `_snprintf_s_l`	`<stdio.h>`
`_snwprintf_s`, `_snwprintf_s_l`	`<stdio.h>` ou `<wchar.h>`

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

Exemplo

// crt_snprintf_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

int snprintf_s_tester( const char * fmt, int x, size_t count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%zd-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %zd; %zd-byte buffer\n",
               count, _countof(dest) );

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );

   printf( "    new contents of dest: '%s'\n", dest );

   return ret;
}

void Examples()
{
   // formatted output string is 9 characters long: "<<<123>>>"
   snprintf_s_tester( "<<<%d>>>", 121, 8 );
   snprintf_s_tester( "<<<%d>>>", 121, 9 );
   snprintf_s_tester( "<<<%d>>>", 121, 10 );

   printf( "\nDestination buffer too small:\n" );

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );

   printf( "\nTruncation examples:\n" );

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );
   printf( "\nSecure template overload example:\n" );

   char dest[10];
   _snprintf( dest, 10, "<<<%d>>>", 12321 );
   // With secure template overloads enabled (see #defines
   // at top of file), the preceding line is replaced by
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );
   // Instead of causing a buffer overrun, _snprintf_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, _snprintf would
   // write 10 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function,
   const wchar_t* file,
   unsigned int line,
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}


count = 8; 10-byte buffer
    new contents of dest: '<<<121>>'

count = 9; 10-byte buffer
    new contents of dest: '<<<121>>>'

count = 10; 10-byte buffer
    new contents of dest: '<<<121>>>'

Destination buffer too small:

count = 10; 10-byte buffer
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Truncation examples:

10-byte buffer; truncation semantics
    new contents of dest: '<<<1221>>'
    truncation did occur

10-byte buffer; truncation semantics
    new contents of dest: '<<<121>>>'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Confira também

E/S de fluxo
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
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

_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Sintaxe

Parâmetros

Retornar valor

Comentários

Resumo do comportamento

Mapeamentos de rotina de texto genérico

Requisitos

Exemplo

Confira também

Comentários

Comentários

Recursos adicionais

`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`