sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Artikel
06/09/2015

Schreiben Sie formatierte Daten in eine Zeichenfolge. Diese Versionen von sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

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

Parameter

buffer
Speicherort für die Ausgabe
sizeOfBuffer
Die maximale Anzahl der zu speichernden Zeichen.
format
Formatsteuerzeichenfolge
argument
Optionale Argumente
locale
Das zu verwendende Gebietsschema.

Weitere Informationen finden Sie unter Formatangaben.

Rückgabewert

Die Anzahl geschriebener Zeichen oder "– 1" bei einem Fehler. Wenn buffer oder format ein NULL-Zeiger ist, geben sprintf_s und swprintf_s -1 zurück und stellen errno auf EINVAL ein.

sprintf_s gibt die Anzahl der in buffer gespeicherten Bytes zurück. Das beendende NULL-Zeichen wird dabei nicht mitgezählt. swprintf_s gibt die Anzahl der in buffer gespeicherten Breitzeichen zurück. Das beendende NULL-Breitzeichen wird dabei nicht mitgezählt.

Hinweise

Die sprintf_s-Funktion formatiert und speichert eine Reihe von Zeichen und Werte in buffer. Jedes argument (falls vorhanden) wird entsprechend der jeweiligen Formatangabe in format konvertiert und ausgegeben. Das Format besteht aus normalen Zeichen und hat die gleiche Form und Funktion wie das format-Argument für printf. Ein NULL-Zeichen wird nach dem letzten geschriebenen Zeichen angefügt. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

Ein Hauptunterschied zwischen sprintf_s und sprintf besteht darin, dass sprintf_s die Formatzeichenfolge auf gültige Formatierungszeichen überprüft. Dagegen überprüft sprintf nur, ob es sich bei der Formatzeichenfolge oder beim Puffer um einen NULL-Zeiger handelt. Wenn bei einer der beiden Überprüfungen ein Fehler auftritt, wird der Handler für ungültige Parameter aufgerufen, wie in Parametervalidierung beschrieben. Wenn die weitere Ausführung zugelassen wird, gibt die Funktion – 1 zurück und stellt errno auf EINVAL ein.

Der andere Hauptunterschied zwischen sprintf_s und sprintf besteht darin, dass sprintf_s einen Längenparameter akzeptiert, der die Größe des Ausgabepuffers in den Zeichen angibt. Wenn der Puffer für den auszugebenden Text zu klein ist, wird er auf eine leere Zeichenfolge festgelegt, und der ungültige Parameterhandler wird aufgerufen. Im Gegensatz zu snprintf garantiert sprintf_s, dass der Puffer mit NULL endet (es sei denn, die Puffergröße ist null).

swprintf_s ist eine Breitzeichen-Version von sprintf_s. Die Zeigerargumente zu swprintf_s sind Breitzeichen-Zeichenfolgen. Die Erkennung von Codierungsfehlern in swprintf_s unterscheidet sich möglicherweise von der in sprintf_s. 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.

Es gibt Versionen von sprintf_s, die eine zusätzliche Kontrolle darüber bieten, was geschieht, wenn der Puffer zu klein ist. Weitere Informationen finden Sie unter _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Anforderungen

Routine	Erforderlicher Header
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> oder <wchar.h>

Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität in der Einführung.

Beispiel

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