_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Artikel
06/09/2015

Schreibt formatierte Daten in eine Zeichenfolge. Diese Versionen von _snprintf, _snprintf_l, _snwprintf, _snwprintf_l enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

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 zu speichern Zeichen oder _TRUNCATE.
format
Formatsteuerzeichenfolge.
argument
Optionale Argumente.
locale
Das zu verwendende Gebietsschema.

Rückgabewert

_snprintf_s gibt die Anzahl von Zeichen zurück, die in buffer gespeicherten und nicht angerechnet das NULL. _snwprintf_s gibt die Anzahl der Breitzeichen zurück, die in buffer gespeicherten und nicht angerechnet das endgültige NULL-Zeichen-Breitzeichen.

Wenn der Speicher, der benötigt wird, die Daten und ein abschließendes NULL-Zeichen speichern, sizeOfBuffer überschreitet, wird der ungültige Parameterhandler aufgerufen, wie in Parametervalidierung beschrieben. Wenn die Ausführung nach Aufruf des Handlers für ungültige Parameter fortgesetzt wird, legen diese Funktionen buffer auf eine leere Zeichenfolge und errno auf ERANGE fest und geben "– 1" zurück.

Wenn buffer oder format ein NULL-Zeiger ist oder wenn count kleiner oder gleich 0 ist, wird der Handler für ungültige Parameter aufgerufen. Wenn die weitere Ausführung zugelassen wird, stellen diese Funktionen errno auf EINVAL ein und geben – 1 zurück.

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 Formatangabe in format konvertiert. Die Formatierung wird mit der printf - Familie von Funktionen konsistent; finden Sie unter Syntax der Formatangabe: printf- und wprintf-Funktionen. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

Wenn _TRUNCATEcount ist, dann wird _snprintf_s so weit der Zeichenfolge, wie im buffer beim Verlassen unterbringen für ein abschließendes NULL-Zeichen passt. Wenn die gesamte Schaltfläche der Zeichenfolge (mit abschließende NULL-Zeichen) in buffer, dann _snprintf_s der Anzahl der geschriebenen Zeichen zurückgibt (ohne das abschließende NULL-Zeichen); Andernfalls gibt _snprintf_s -1 zurück, um anzugeben, dass das Abschneiden aufgetreten ist.

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

_snwprintf_s ist eine Breitzeichen-Version von _snprintf_s. Die Zeigerargumente zu _snwprintf_s sind Breitzeichen-Zeichenfolgen. Erkennung von Codierungsfehlern in _snwprintf_s sich möglicherweise von der im _snprintf_s. _snwprintf_s, wie swprintf_s, schreibt Ausgabe in eine Zeichenfolge anstatt an ein Silverlight-Ziel des Typs FILE.

Die Versionen dieser Funktionen mit dem _l-Suffix sind beinahe identisch, verwenden jedoch den ihnen übergebenen Gebietsschemaparameter anstelle des aktuellen Threadgebietsschemas.

In C++ wird die Verwendung dieser Funktionen durch Vorlagenüberladungen vereinfacht; die Überladungen können automatisch Rückschlüsse auf die Pufferlänge ziehen (wodurch kein Größenargument mehr angegeben werden muss), und sie können automatisch die älteren, nicht sicheren Funktionen durch ihre neueren, sicheren Entsprechungen ersetzen. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Zuordnung generischer Textroutinen

Tchar.h-Routine	_UNICODE und _MBCS nicht definiert	_MBCS definiert	_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 zur Kompatibilität finden Sie unter 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();
}