snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Schreibt formatierte Daten in eine Zeichenfolge. Sicherere Versionen dieser Funktionen sind verfügbar; siehe _snprintf_s, , _snprintf_s_l, . _snwprintf_s_l_snwprintf_s

Syntax

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

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

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

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

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

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

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

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

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

Parameter

buffer
Speicherort für die Ausgabe.

count
Maximale Anzahl der zu schreibenden Zeichen. Für die Funktionen, die verwendet wchar_twerden, ist es die maximale Anzahl von breiten Zeichen, die geschrieben werden sollen.

format
Formatsteuerzeichenfolge.

argument
Optionale Argumente.

locale
Das Gebietsschema, das zum Formatieren der Ausgabe verwendet werden soll.

Weitere Informationen finden Sie unter Formatspezifikationssyntax: printf und wprintf Funktionen.

Rückgabewert

Die Anzahl der Zeichen, die in den Puffer geschrieben wurden, wenn count sie ignoriert wurden. Die Anzahl enthält nicht das Endzeichen NULL .

Let len be the length of the formatted data string, not including the endating NULL.
Bei allen Funktionen, wenn len < count, dann len Zeichen gespeichert bufferwerden, wird ein Null-Terminator angefügt, und die Anzahl der geschriebenen Zeichen, nicht einschließlich der Beendigung NULL, wird zurückgegeben.

Die breiten Zeichenversionen dieser Funktionen geben die Anzahl der geschriebenen Zeichen zurück, nicht einschließlich des Beendens NULL.

Ausführliche Informationen finden Sie in der Verhaltenszusammenfassung .

Hinweise

Beginnend mit der UCRT in Visual Studio 2015 und Windows 10 ist snprintf nicht mehr identisch mit _snprintf. Das snprintf Verhalten ist jetzt C99 Standard konform. Der Unterschied besteht darin, snprintf dass beim Auslaufen des Puffers null das Ende des Puffers durch Null beendet und die Anzahl der Zeichen zurückgegeben wird, die erforderlich wären, während _snprintf der Puffer nicht null beendet und -1 zurückgegeben wird. Enthält außerdem ein weiteres Zeichen in der Ausgabe, snprintf() da er den Puffer nicht null beendet.

• snprintf und die _snprintf Familie der Funktionen formatieren und speichern count oder weniger Zeichen in buffer.
• snprintf speichert immer ein endendes NULL Zeichen, wobei die Ausgabe bei Bedarf abgeschnitten wird.
• Wenn snprintf ein Wert >count - 1 zurückgegeben wird, wurde die Ausgabe abgeschnitten.
• Die _snprintf Funktionsfamilie fügt nur ein Endzeichen NULL an, wenn die formatierte Zeichenfolgenlänge streng kleiner als count Zeichen ist.
• Jedes argument (falls vorhanden) wird entsprechend der jeweiligen Formatangabe in formatkonvertiert und ausgegeben. Das Format besteht aus normalen Zeichen und hat die gleiche Form und Funktion wie das format-Argument für printf. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

Verhaltenszusammenfassung

Für die folgende Tabelle:

• Lassen Sie uns sizeOfBuffer die Größe von buffer. Wenn die Funktion einen char Puffer verwendet, befindet sich die Größe in Byte. Wenn die Funktion einen wchar_t Puffer verwendet, gibt die Größe die Anzahl der 16-Bit-Wörter an.
• Lassen Sie uns len die Größe der formatierten Daten sein. Wenn die Funktion einen char Puffer verwendet, befindet sich die Größe in Byte. Wenn die Funktion einen wchar_t Puffer verwendet, gibt die Größe die Anzahl der 16-Bit-Wörter an.
• Zeichen beziehen sich auf char Zeichen für Funktionen, die einen char Puffer verwenden, und zeichen wchar_t für Funktionen, die einen wchar_t Puffer verwenden.
• Weitere Informationen zum ungültigen Parameterhandler finden Sie unter Parameterüberprüfung.

Bedingung	Verhalten	Rückgabewert	errno	Ruft ungültige Parametertyphandler auf
Erfolg	Schreibt die Zeichen mithilfe der angegebenen Formatzeichenfolge in den Puffer.	Die Anzahl der geschriebenen Zeichen.	Nicht zutreffend	Nein
Codierungsfehler während der Formatierung	Wenn die Verarbeitung des Zeichenfolgenbezeichners oder ZSder Formatierungsspezifikationsverarbeitung angehalten wird, wird am Anfang des Puffers ein NULL Zeichenfolgenbezeichner splatziert.	-1	EILSEQ (42)	Nein
Codierungsfehler während der Formatierung	Bei der Verarbeitung des Zeichenbezeichners c oder Cwird das ungültige Zeichen übersprungen. Die Anzahl der geschriebenen Zeichen wird für das übersprungene Zeichen nicht erhöht, oder es werden keine Daten dafür geschrieben. Die Verarbeitung der Formatspezifikation wird fortgesetzt, nachdem der Bezeichner mit dem Codierungsfehler übersprungen wurde.	Die Anzahl der geschriebenen Zeichen, nicht einschließlich des Beendens NULL.	EILSEQ (42)	Nein
buffer == NULL und count != 0	Wenn die Ausführung nach ausführung eines ungültigen Parameterhandlers fortgesetzt wird, wird ein negativer Wert festgelegt errno und zurückgegeben.	-1	EINVAL (22)	Ja
count == 0	Die Anzahl der Zeichen, die geschrieben wurden, nicht einschließlich des Beendens NULL. Sie können dieses Ergebnis verwenden, um genügend Pufferraum für die Zeichenfolge und eine Beendigung NULLzuzuweisen, und dann die Funktion erneut aufrufen, um den Puffer auszufüllen.	Nicht zutreffend	Nein
count < 0	Unsicher: Der Wert wird als nicht signiert behandelt, wahrscheinlich wird ein großer Wert erstellt, der dazu führt, dass der Speicher, der dem Puffer folgt, überschrieben wird.	Die Anzahl der geschriebenen Zeichen	Nicht zutreffend	Nein
count < sizeOfBuffer und len <= count	Alle Daten werden geschrieben, und eine Beendigung NULL wird angefügt.	Die Anzahl der geschriebenen Zeichen, nicht einschließlich des Beendens NULL.	Nicht zutreffend	Nein
count < sizeOfBuffer und len > count	Die ersten count-1 Zeichen werden gefolgt von einem Null-Terminator geschrieben.	Die Anzahl der Zeichen, die geschrieben wurden, stimmte count mit der Anzahl der auszuzugebenden Zeichen überein, nicht einschließlich des Null-Terminators.	Nicht zutreffend	Nein
count >= sizeOfBuffer und len < sizeOfBuffer	Alle Daten werden mit einer Beendigung NULLgeschrieben.	Die Anzahl der geschriebenen Zeichen, nicht einschließlich des Beendens NULL.	Nicht zutreffend	Nein
count >= sizeOfBuffer und len >= sizeOfBuffer	Unsicher: Überschreibt den Speicher, der dem Puffer folgt.	Die Anzahl der geschriebenen Zeichen, nicht einschließlich des Beendens NULL.	Nicht zutreffend	Nein
format == NULL	Es werden keine Daten geschrieben. Wenn die Ausführung nach ausführung eines ungültigen Parameterhandlers fortgesetzt wird, wird ein negativer Wert festgelegt errno und zurückgegeben.	-1	EINVAL (22)	Ja

Informationen zu diesen und anderen Fehlercodes finden Sie unter , , errno, _sys_errlistund _sys_nerr._doserrno

Wichtig

Stellen Sie sicher, dass format keine benutzerdefinierte Zeichenfolge ist. Da die _snprintf Funktionen keine NULL-Beendigung garantieren , insbesondere, wenn der Rückgabewert lautet count– stellen Sie sicher, dass sie mit Code gefolgt werden, der den Null-Endator hinzufügt. Weitere Informationen finden Sie unter Vermeiden von Pufferüberläufen.

Ab Windows 10, Version 2004 (Build 19041), druckt die printf Funktionsfamilie exakt repräsentierbare Gleitkommazahlen gemäß den IEEE 754-Regeln zum Runden. In früheren Versionen von Windows würden exakt dargestellte Gleitkommazahlen, die auf "5" enden, immer aufgerundet. IEEE 754 gibt an, dass sie auf die nächstgelegene gerade Ziffer runden müssen (auch bekannt als "Banker es Rounding"). Beispielsweise sollten beide printf("%1.0f", 1.5) auf printf("%1.0f", 2.5) 2 gerundet werden. Zuvor würde 1,5 auf 2 und 2,5 runden auf 3. Diese Änderung wirkt sich nur auf genau darstellbare Zahlen aus. Beispielsweise wird 2.35 (die, wenn sie im Arbeitsspeicher dargestellt wird, näher an 2.35000000000000008) weiter auf 2,4 aufgerundet. Das Runden dieser Funktionen berücksichtigt nun auch den gleitkommafreien Rundungsmodus, der von fesetround. Zuvor wählte das Rundungsverhalten immer aus FE_TONEAREST . Diese Änderung betrifft nur Programme, die mit Visual Studio 2019, Version 16.2 und höher erstellt wurden. Zum Verwenden des älteren Gleitkomma-Rundungsverhaltens mit legacy_stdio_float_rounding.obj.

_snwprintf ist eine Breitzeichen-Version von _snprintf. Die Zeigerargumente zu _snwprintf sind Breitzeichen-Zeichenfolgen. Die Erkennung von Codierungsfehlern kann _snwprintf sich von der Erkennung unterscheiden._snprintf _snwprintfgenauso wie swprintfschreibt die Ausgabe in eine Zeichenfolge anstatt in ein Ziel vom Typ FILE.

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

In C++ verfügen diese Funktionen über Vorlagenüberladungen, die die neueren, sichereren Entsprechungen aufrufen. Weitere Informationen finden Sie unter "Sichere Vorlagenüberladungen".

Generische Textroutinzuordnungen

Tchar.h Routine	_UNICODE und _MBCS nicht definiert	_MBCS Definiert	_UNICODE Definiert
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Anforderungen

Routine	Erforderlicher Header
snprintf, _snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> oder <wchar.h>

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

// crt_snprintf.c
// compile with: /W3
#include <stdio.h>
#include <stdlib.h>

#if !defined(__cplusplus)
typedef int bool;
const bool true = 1;
const bool false = 0;
#endif

#define FAIL 0 // change to 1 and see what happens

int main(void)
{
   char buffer[200];
   const static char s[] = "computer"
#if FAIL
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
#endif
   ;
   const char c = 'l';
   const int i = 35;
#if FAIL
   const double fp = 1e300; // doesn't fit in the buffer
#else
   const double fp = 1.7320534;
#endif
   /* !subtract one to prevent "squeezing out" the terminal null! */
   const int bufferSize = sizeof(buffer)/sizeof(buffer[0]) - 1;
   int bufferUsed = 0;
   int bufferLeft = bufferSize - bufferUsed;
   bool bSuccess = true;
   buffer[0] = 0;

   /* Format and print various data: */

   if (bufferLeft > 0)
   {
      int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
      bufferLeft, "   String: %s\n", s ); // C4996
      // Note: _snprintf is deprecated; consider _snprintf_s instead
      if (bSuccess = (perElementBufferUsed >= 0))
      {
         bufferUsed += perElementBufferUsed;
         bufferLeft -= perElementBufferUsed;
         if (bufferLeft > 0)
         {
            int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
            bufferLeft, "   Character: %c\n", c ); // C4996
            if (bSuccess = (perElementBufferUsed >= 0))
            {
               bufferUsed += perElementBufferUsed;
               bufferLeft -= perElementBufferUsed;
               if (bufferLeft > 0)
               {
                  int perElementBufferUsed = _snprintf(&buffer
                  [bufferUsed], bufferLeft, "   Integer: %d\n", i ); // C4996
                  if (bSuccess = (perElementBufferUsed >= 0))
                  {
                     bufferUsed += perElementBufferUsed;
                     bufferLeft -= perElementBufferUsed;
                     if (bufferLeft > 0)
                     {
                        int perElementBufferUsed = _snprintf(&buffer
                        [bufferUsed], bufferLeft, "   Real: %f\n", fp ); // C4996
                        if (bSuccess = (perElementBufferUsed >= 0))
                        {
                           bufferUsed += perElementBufferUsed;
                        }
                     }
                  }
               }
            }
         }
      }
   }

   if (!bSuccess)
   {
      printf("%s\n", "failure");
   }
   else
   {
      /* !store null because _snprintf doesn't necessarily (if the string
       * fits without the terminal null, but not with it)!
       * bufferUsed might be as large as bufferSize, which normally is
       * like going one element beyond a buffer, but in this case
       * subtracted one from bufferSize, so we're ok.
       */
      buffer[bufferUsed] = 0;
      printf( "Output:\n%s\ncharacter count = %d\n", buffer, bufferUsed );
   }
   return EXIT_SUCCESS;
}

Output:
   String: computer
   Character: l
   Integer: 35
   Real: 1.732053

character count = 69

Siehe auch

Stream-E/A
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
vprintf-Funktionen