_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Artikel
02/26/2013

Schreibt formatierte Daten in eine Zeichenfolge.Dies sind Versionen von _snprintf, _snprintf_l, _snwprintf, _snwprintf_l mit beschrieben, wie unter Security Enhancements in Sicherheitsfeatures im 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

Parameter

buffer
Speicherort für die Ausgabe.
sizeOfBuffer
Die Größe des Speicherorts für die Ausgabe.Größe in bytes für _snprintf_s oder Größe in words für _snwprintf_s.
Count
Maximale Anzahl von Zeichen oder _TRUNCATEzu speichern.
format
Formatsteuerzeichenfolge.
argument
Optionale Argumente.
locale
Das zu verwendende Gebietsschema.

Rückgabewert

_snprintf_s gibt die Anzahl von Zeichen zurück, die in buffergespeichert werden und keine zählt das NULL._snwprintf_s gibt die Anzahl der Breitzeichen zurück, die in buffergespeichert werden und keine zählt das Breitzeichen des abschließenden NULL-Zeichens.

Wenn der Speicher, der die Daten und ein abschließendes NULL-Zeichen zu speichern sizeOfBuffererforderlich ist, ungültige Parameter überschreitet, wird der Ereignishandler aufgerufen, wie in Parametervalidierungbeschrieben.Wenn die Ausführung nach dem ungültigen Parameter, wird für diese Funktionen buffer auf eine leere Zeichenfolge fest, und legen errno zu ERANGEreturn -1 fest.

Wenn bufferNULLformat oder ein Zeiger ist oder wenn count kleiner oder gleich null ist, wird der Ereignishandler aufgerufen. ungültige ParameterWenn die Ausführung fortgesetzt werden kann, darf dieses Features zu EINVAL und legen errno return -1.

Weitere Informationen über diese und andere Fehlercodes finden Sie unter _doserrno, errno, _sys_errlist und _sys_nerr.

Hinweise

Die _snprintf_s-Funktion formatiert und speichert count oder weniger Zeichen in buffer und fügt ein abschließendes NULL-Zeichen an.Jedes Argument (falls vorhanden) wird und Ausgabe entsprechend der entsprechenden Formatelement in formatkonvertiert.Die Formatierung wird mit der printf-Funktionsreihe konsistent. Weitere Informationen finden Sie unter Syntax der Formatangabe: printf- und wprintf-Funktionen.Wenn das Kopieren zwischen Zeichenfolgen auftritt, die sich überschneiden, ist das Verhalten nicht definiert.

Wenn count_TRUNCATEist, schreibt _snprintf_s so weit wie in der Zeichenfolge, bei der buffer Lassen des Für für ein abschließendes NULL-Zeichen passt.Wenn die gesamte Passung der Zeichenfolge NULL-Zeichen (mit abschließendem) in buffer, _snprintf_s die Anzahl der geschriebenen Zeichen zurück (ohne das abschließende NULL-Zeichen). Andernfalls gibt _snprintf_s -1 zurück, um anzugeben, dass Abschneiden aufgetreten ist.

Sicherheitshinweis
Stellen Sie sicher, dass format keine benutzerdefinierte Zeichenfolge ist.

_snwprintf_s ist eine Breitzeichen-Version von _snprintf_s. Zeiger auf die Argumente _snwprintf_s sind Zeichenfolgen mit Breitzeichen.Erkennung von Codierungsfehlern in _snwprintf_s kann sich von der in _snprintf_s._snwprintf_s, wie swprintf_s, schreibt die Ausgabe in einer Zeichenfolge anstatt an ein Ziel des Typs FILE.

Die Versionen dieser Funktionen mit dem _l Suffix sind identisch, mit der Ausnahme, dass sie verwenden den Gebietsschemaparameter, der anstelle des aktuellen Threads gebietsschemas übergeben wird.

In C++ unter Verwendung dieser Funktionen wird von Vorlagen Operatoren vereinfacht. Die Überladungen können die Pufferlänge (die Anforderung automatisch beseitigend ableiten, die ein Argument angegeben) und können nicht-sicheren, die älteren Funktionen über ihre Äquivalente sicheren, aktuelleren automatisch ersetzen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Zuweisung generischer Textroutinen

Tchar.h-Routine	_UNICODE als auch _MBCS nicht definiert	_MBCS definieren	_UNICODE definiert
_sntprintf_s	_snprintf_s	_snprintf_s	_snwprintf_s
_sntprintf_s_l	_snprintf_s_l	_snprintf_s_l	_snwprintf_s_l

Anforderungen

Routine	Erforderlicher Header
_snprintf_s, _snprintf_s_l	<stdio.h>
_snwprintf_s, _snwprintf_s_l	<stdio.h> oder <wchar.h>

Weitere Informationen finden Sie unter Kompatibilität Kompatibilität in der Einführung.

Beispiel

// 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();
}