_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Artykuł
06/09/2015

Zapisuje sformatowane dane na ciąg.Są to wersje _snprintf, _snprintf_l, _snwprintf, _snwprintf_l z rozszerzeń zabezpieczeń opisane w Funkcje zabezpieczeń w CRT.

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

Parametry

buffer
Lokalizacja przechowywania danych wyjściowych.
sizeOfBuffer
Rozmiar miejsca przechowywania danych wyjściowych.Size in bytes for _snprintf_s or size in words for _snwprintf_s.
Count
Maksymalna liczba znaków do przechowywania, lub _TRUNCATE.
format
Ciąg formatu formantu.
argument
Opcjonalne argumenty.
locale
Ustawienia regionalne, aby użyć.

Wartość zwracana

_snprintf_sZwraca liczbę znaków przechowywanych w buffer, nie licząc kończącego znaku null._snwprintf_sZwraca liczbę znaków szerokości przechowywane w buffer, nie licząc zakończeń szerokiego znaku null.

Jeśli przekracza pamięci potrzebnej do przechowywania danych i zakończeń null sizeOfBuffer, wywoływana jest funkcja obsługi nieprawidłowy parametr, jak opisano w Sprawdzanie poprawności parametru.Jeśli wykonywanie jest kontynuowane po obsługi nieprawidłowy parametr, ustaw te funkcje buffer ciąg pusty, ustaw errno do ERANGEi zwraca –1.

Jeśli buffer lub format jest NULL wskaźnik, lub jeśli count jest mniejsza lub równa zeru, wywoływana jest funkcja obsługi nieprawidłowy parametr.Jeśli wykonanie może kontynuować, ustaw te funkcje errno do EINVAL i zwraca –1.

Aby uzyskać informacje na temat tych i innych kodów błędów, zobacz _doserrno, errno, _sys_errlist i _sys_nerr.

Uwagi

_snprintf_s Funkcji formaty i Sklepy count lub mniej znaków w buffer i dołącza zakończeń null.Każdy argument (jeśli ma zastosowanie) jest konwertowane i wyjściowe zgodnie ze specyfikacją odpowiedni format w format.Formatowanie jest zgodny z printf rodziny funkcji; see Składnia specyfikacji formatu: funkcje printf i wprintf.Jeśli kopiowanie występuje między ciągami, które się pokrywają, zachowanie jest niezdefiniowane.

Jeśli count jest _TRUNCATE, następnie _snprintf_s zapisuje tyle ciąg będą mieści się w buffer , pozostawiając pomieszczenia kończącego NULL.Jeśli cały ciąg (z zakończeń null) mieści się w buffer, następnie _snprintf_s zwraca liczbę znaków, napisane (z wyłączeniem zakończeń null); w przeciwnym razie _snprintf_s zwraca wartość -1, aby wskazać, że obcinania wystąpił.

Uwaga dotycząca zabezpieczeń
Zapewnić, że format nie jest ciągiem zdefiniowane przez użytkownika.

_snwprintf_sjest to wersja szerokich znaków _snprintf_s; argumenty wskaźnik do _snwprintf_s są ciągami szerokich znaków.Wykrywanie błędów kodowania _snwprintf_s może różnić się od tej w _snprintf_s._snwprintf_s, takich jak swprintf_s, zapisuje dane wyjściowe na ciąg znaków, a nie do miejsca docelowego typu FILE.

Wersje te funkcje, z _l sufiks są identyczne, z wyjątkiem, że używają oni przekazany zamiast bieżące ustawienia regionalne wątku parametr ustawień regionalnych.

W języku C++ korzystając z tych funkcji jest uproszczona poprzez overloads szablonu; overloads można automatycznie rozpoznać długość buforu (eliminując konieczność należy określić argument rozmiar) i automatycznie można zastąpić starszych, które nie są bezpieczne funkcje z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Tekst rodzajowy rutynowych mapowania

Procedura TCHAR.h	_UNICODE i _MBCS nie zdefiniowane	_MBCS, definicja	_UNICODE, definicja
_sntprintf_s	_snprintf_s	_snprintf_s	_snwprintf_s
_sntprintf_s_l	_snprintf_s_l	_snprintf_s_l	_snwprintf_s_l

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
_snprintf_s, _snprintf_s_l	<stdio.h>
_snwprintf_s, _snwprintf_s_l	<stdio.h> lub <wchar.h>

Informacji dotyczących zgodności, zobacz zgodności we wprowadzeniu.

Przykład

// 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, int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%d-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %d; %d-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();
}