Freigeben über

snprintf, , _snprintf_snprintf_l, , _snwprintf_snwprintf_l

  • Artikel

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 Behavior Rückgabewert errno Ruft ungültige Parametertyphandler auf
Erfolgreich Schreibt die Zeichen mithilfe der angegebenen Formatzeichenfolge in den Puffer. Die Anzahl der geschriebenen Zeichen. N/V No
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) No
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) No
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. N/V No
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 N/V No
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. N/V No
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. N/V No
count >= sizeOfBuffer und len < sizeOfBuffer Alle Daten werden mit einer Beendigung NULLgeschrieben. Die Anzahl der geschriebenen Zeichen, nicht einschließlich des Beendens NULL. N/V No
count >= sizeOfBuffer und len >= sizeOfBuffer Unsicher: Überschreibt den Speicher, der dem Puffer folgt. Die Anzahl der geschriebenen Zeichen, nicht einschließlich des Beendens NULL. N/V No
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) gibt die printf-Funktionsfamilie exakt darstellbare Fließkommazahlen gemäß den IEEE 754-Rundungsregeln aus. In früheren Versionen von Windows wurden exakt darstellbare Fließkommazahlen, die auf „5“ endeten, immer aufgerundet. IEEE 754 besagt, dass sie auf die nächste gerade Ziffer gerundet werden müssen (auch bekannt als „Unverzerrte Rundung“). Beispielsweise sollten sowohl printf("%1.0f", 1.5) als auch printf("%1.0f", 2.5) auf 2 gerundet werden. Zuvor wurde 1,5 auf 2 und 2,5 auf 3 gerundet. Diese Änderung wirkt sich nur auf genau darstellbare Zahlen aus. 2,35 (was bei der Darstellung im Speicher näher an 2,35000000000000008 liegt) rundet zum Beispiel weiterhin auf 2,4 auf. Die Rundung durch diese Funktionen berücksichtigt nun auch den Fließkomma-Rundungsmodus, der durch fesetroundfestgelegt wird. Zuvor wählte die Rundung immer das FE_TONEAREST-Verhalten. 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 Secure Template Overloads.

Mapping generischer Textroutinen

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_lswprintf, , _swprintf_l__swprintf_l
fprintf, , _fprintf_lfwprintf_fwprintf_l
printf, , _printf_lwprintf_wprintf_l
scanf, , _scanf_lwscanf_wscanf_l
sscanf, , _sscanf_lswscanf_swscanf_l
vprintf -Funktionen