_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Artikel
06/09/2015

Schreibt formatierte Daten in eine Zeichenfolge. Sicherere Versionen dieser Funktionen sind verfügbar. Informationen dazu finden Sie unter _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

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
Die maximale Anzahl der zu speichernden Zeichen.
format
Formatsteuerzeichenfolge.
argument
Optionale Argumente.
locale
Das zu verwendende Gebietsschema.

Weitere Informationen finden Sie unter Syntax der Formatangabe: printf- und wprintf-Funktionen.

Rückgabewert

Zulassen, dass len die Länge der formatierten Datenzeichenfolge ist, ausschließlich der abschließenden 0 (null). len und count sind Bytes für _snprintf, Breitzeichen für _snwprintf.

Wenn len < count, len-Zeichen in buffer gespeichert werden, wird ein NULL-Terminator angefügt, und len wird zurückgegeben.

Wenn len = count, len-Zeichen in buffer gespeichert werden, wird kein NULL-Terminator angefügt, und len wird zurückgegeben.

Wenn len > count, count-Zeichen in buffer gespeichert werden, wird kein NULL-Terminator angefügt, und ein negativer Wert wird zurückgegeben.

Wenn buffer ein NULL-Zeiger ist und count NULL ist, wird len als Anzahl der Zeichen zurückgegeben, die zur Formatierung der Ausgabe erforderlich sind, ausschließlich der abschließenden NULL. Um einen erfolgreichen Aufruf mit denselben argument- und locale-Parametern durchzuführen, ordnen Sie einen Puffer zu, der mindestens len + 1 Zeichen enthält.

Wenn buffer ein NULL-Zeiger ist und count ungleich NULL ist oder wenn format ein NULL-Zeiger ist, wird der ungültige Parameterhandler ausgelöst, wie in Parametervalidierung beschrieben. Wenn die weitere Ausführung zugelassen wird, geben diese Funktionen "– 1" zurück und legen errno auf EINVAL fest.

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

Hinweise

Die Funktion _snprintf formatiert und speichert count oder weniger Zeichen in buffer und fügt ein abschließendes NULL-Zeichen an, wenn die Länge der formatierten Zeichenfolge streng genommen weniger als count Zeichen ist. 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. Wenn der Kopiervorgang zwischen Zeichenfolgen ausgeführt wird, die sich überschneiden, ist das Verhalten nicht definiert.

Sicherheitshinweis
Stellen Sie sicher, dass format keine benutzerdefinierte Zeichenfolge ist.Da diese Funktion keinen NULL-Abschluss garantiert, achten Sie darauf, insbesondere wenn der Rückgabewert count, dass ihm Code folgt, der den NULL-Terminator hinzufügt.Weitere Informationen finden Sie unter Vermeiden von Pufferüberläufen.

_snwprintf ist eine Breitzeichen-Version von _snprintf. Die Zeigerargumente zu _snwprintf sind Breitzeichen-Zeichenfolgen. Die Erkennung von Codierungsfehlern in _snwprintf unterscheidet sich möglicherweise von der in _snprintf. _snwprintf genauso wie swprintf schreibt 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++ haben diese Funktionen Vorlagenüberladungen, mit denen die neueren, sicheren Entsprechungen dieser Funktionen aufgerufen werden. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Zuordnung 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_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 nul! */
   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 nul because _snprintf doesn't necessarily (if the string 
       * fits without the terminal nul, 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;
}