Namespaces
Variants

vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s

Von de.cppreference.net
< c | io
 
 
Datei-Eingabe/Ausgabe
Typen und Objekte
        
Funktionen
Dateizugriff
(C95)
Unformatierte Ein-/Ausgabe
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)

Formatierte Eingabe
Direkte Ein-/Ausgabe
Formatierte Ausgabe
Dateipositionierung
Fehlerbehandlung
Operationen auf Dateien
 
Definiert in Header <stdio.h>
int vprintf( const char* format, va_list vlist );
(1) (bis C99)
int vprintf( const char* restrict format, va_list vlist );
(seit C99)
int vfprintf( FILE* stream, const char* format, va_list vlist );
(2) (bis C99)
int vfprintf( FILE* restrict stream, const char* restrict format,
              va_list vlist );
(seit C99)
int vsprintf( char* buffer, const char* format, va_list vlist );
(3) (bis C99)
int vsprintf( char* restrict buffer, const char* restrict format,
              va_list vlist );
(seit C99)
int vsnprintf( char* restrict buffer, size_t bufsz,
               const char* restrict format, va_list vlist );
(4) (seit C99)
int vprintf_s( const char* restrict format, va_list vlist );
(5) (seit C11)
int vfprintf_s( FILE* restrict stream, const char* restrict format,
                va_list vlist );
(6) (seit C11)
int vsprintf_s( char* restrict buffer, rsize_t bufsz,
                const char* restrict format, va_list vlist );
(7) (seit C11)
int vsnprintf_s( char* restrict buffer, rsize_t bufsz,
                 const char* restrict format, va_list vlist );
(8) (seit C11)

Lädt die Daten von den durch vlist festgelegten Speicherorten, wandelt sie in Zeichenkettenäquivalente um und schreibt die Ergebnisse in verschiedene Ziele.

1) Schreibt die Ergebnisse nach stdout.
2) Schreibt die Ergebnisse in einen Dateistrom stream.
3) Schreibt die Ergebnisse in eine Zeichenkette buffer.
4) Schreibt die Ergebnisse in eine Zeichenkette buffer. Es werden höchstens bufsz - 1 Zeichen geschrieben. Die resultierende Zeichenkette wird mit einem Nullzeichen abgeschlossen, es sei denn, bufsz ist Null. Wenn bufsz Null ist, wird nichts geschrieben und buffer darf ein Nullzeiger sein, jedoch wird der Rückgabewert (Anzahl der Bytes, die geschrieben worden wären, ohne den Nullterminator) trotzdem berechnet und zurückgegeben.
5-8) Wie (1-4), mit dem Unterschied, dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler-Funktion aufgerufen wird:
  • der Konvertierungsspezifizierer %n ist in format
  • vorhanden, eines der Argumente, das %s entspricht, ist ein Nullzeiger,
  • format oder buffer ist ein Nullzeiger,
  • bufsz ist Null oder größer als RSIZE_MAX
  • , Kodierungsfehler treten bei Zeichenketten- und Zeichen-Konvertierungsspezifizierern auf,
  • (nur für vsprintf_s), die in buffer zu speichernde Zeichenkette (einschließlich des abschließenden Nullzeichens) würde bufsz
überschreiten. Wie bei allen geprüften Funktionen sind vprintf_s, vfprintf_s, vsprintf_s und vsnprintf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ als ganzzahlige Konstante 1 definiert, bevor <stdio.h> eingebunden wird.

Parameter

stream - Ausgabedateistrom, in den geschrieben wird
buffer - Zeiger auf eine Zeichenkette, in die geschrieben wird
bufsz - es können bis zu bufsz - 1 Zeichen geschrieben werden, plus der Nullterminator
format - Zeiger auf eine nullterminierte Zeichenkette, die angibt, wie die Daten interpretiert werden sollen
vlist - Liste variabler Argumente, die die zu druckenden Daten enthält.

Die Zeichenkette format besteht aus gewöhnlichen Byte-Zeichen (außer %), die unverändert in den Ausgabestrom kopiert werden, und Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat das folgende Format:

  • einleitendes %-Zeichen.
  • (optional) ein oder mehrere Flags, die das Verhalten der Konvertierung modifizieren:
  • -: Das Ergebnis der Konvertierung wird linksbündig im Feld ausgerichtet (standardmäßig ist es rechtsbündig).
  • +: Das Vorzeichen von vorzeichenbehafteten Konvertierungen wird dem Ergebnis immer vorangestellt (standardmäßig wird dem Ergebnis nur ein Minus vorangestellt, wenn es negativ ist).
  • Leerzeichen: Wenn das Ergebnis einer vorzeichenbehafteten Konvertierung nicht mit einem Vorzeichenzeichen beginnt oder leer ist, wird dem Ergebnis ein Leerzeichen vorangestellt. Es wird ignoriert, wenn das +-Flag vorhanden ist.
  • #: Es wird die alternative Darstellung der Konvertierung durchgeführt. Siehe die Tabelle unten für genaue Auswirkungen; andernfalls ist das Verhalten undefiniert.
  • 0: Bei Ganzzahl- und Gleitkommazahlenkonvertierungen werden führende Nullen zur Auffüllung des Feldes anstelle von Leerzeichen verwendet. Bei Ganzzahlen wird es ignoriert, wenn die Genauigkeit explizit angegeben ist. Bei anderen Konvertierungen führt die Verwendung dieses Flags zu undefiniertem Verhalten. Es wird ignoriert, wenn das --Flag vorhanden ist.
  • (optional) Ganzzahlwert oder *, der die minimale Feldbreite angibt. Das Ergebnis wird bei Bedarf mit Leerzeichen aufgefüllt (standardmäßig) auf der linken Seite, wenn rechtsbündig, oder auf der rechten Seite, wenn linksbündig. Im Fall von * wird die Breite durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument und dem Argument, das die Genauigkeit liefert, falls vorhanden, erscheint. Wenn der Wert des Arguments negativ ist, führt dies zu einem angegebenen --Flag und positiver Feldbreite (Hinweis: Dies ist die Mindestbreite: Der Wert wird niemals abgeschnitten.).
  • (optional) . gefolgt von einer ganzen Zahl oder * oder nichts, was die Genauigkeit der Konvertierung angibt. Im Fall von * wird die Genauigkeit durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument, aber nach dem Argument, das die minimale Feldbreite liefert, falls vorhanden, erscheint. Wenn der Wert dieses Arguments negativ ist, wird es ignoriert. Wenn weder eine Zahl noch * verwendet wird, wird die Genauigkeit als Null angenommen. Siehe die Tabelle unten für genaue Auswirkungen der Genauigkeit.
  • (optional) Längenmodifikator, der die Größe des Arguments angibt (in Kombination mit dem Format-Konvertierungsspezifizierer gibt er den Typ des entsprechenden Arguments an).
  • Konvertierungsformat-Spezifizierer.

Die folgenden Formatspezifizierer sind verfügbar:

Konvertierungs
Spezifizierer
Erklärung Erwarteter
Argumenttyp
Längenmodifikator→ hh h keiner l ll j z t L
Nur seit C99 verfügbar→ Ja Ja Ja Ja Ja
% Schreibt wörtliches %. Die vollständige Konvertierungsspezifikation muss %% sein. N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Schreibt ein einzelnes Zeichen.

  • Das Argument wird zuerst in unsigned char konvertiert.
  • Wenn der l-Modifikator verwendet wird, wird das Argument zuerst in eine Zeichenkette konvertiert, als ob mit %ls und einem wchar_t[2]-Argument.
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

Schreibt eine Zeichenkette.

  • Das Argument muss ein Zeiger auf das erste Element eines Zeichenfeldes sein.
  • Genauigkeit gibt die maximale Anzahl von Bytes an, die geschrieben werden sollen. Wenn Genauigkeit nicht angegeben ist, wird jedes Byte bis einschließlich des ersten Nullterminators geschrieben (ohne diesen).
  • Wenn der l-Spezifizierer verwendet wird, muss das Argument ein Zeiger auf das erste Element eines Feldes von wchar_t sein, das in ein char-Feld konvertiert wird, als ob durch einen Aufruf von wcrtomb mit nullinitialisiertem Konvertierungszustand.
N/A N/A
char*
wchar_t*
N/A N/A N/A N/A N/A
d
i

Konvertiert eine vorzeichenbehaftete ganze Zahl in eine Dezimaldarstellung [-]dddd.

  • Genauigkeit gibt die Mindestanzahl von Ziffern an, die erscheinen sollen. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, führt die Konvertierung zu keinen Zeichen.
  • Für den z-Modifikator ist der erwartete Argumenttyp die vorzeichenbehaftete Version von size_t.
signed char
short
int
long
long long
intmax_t
※
ptrdiff_t
N/A
b
B (optional)

(C23)

Konvertiert eine vorzeichenlose ganze Zahl in eine binäre Darstellung bbbb.

  • Genauigkeit gibt die Mindestanzahl von Ziffern an, die erscheinen sollen. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, führt die Konvertierung zu keinen Zeichen.
  • In der alternativen Implementierung 0b wird 0B dem Ergebnis vorangestellt, wenn der konvertierte Wert ungleich Null ist.
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
uintmax_t
size_t
vorzeichenlose Version von ptrdiff_t
N/A
o

Konvertiert eine vorzeichenlose ganze Zahl in eine oktale Darstellung oooo.

  • Genauigkeit gibt die Mindestanzahl von Ziffern an, die erscheinen sollen. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, führt die Konvertierung zu keinen Zeichen.
  • In der alternativen Implementierung wird die Genauigkeit bei Bedarf erhöht, um eine führende Null zu schreiben. In diesem Fall wird, wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, ein einzelnes 0 geschrieben.
N/A
x
X

Konvertiert eine vorzeichenlose ganze Zahl in eine hexadezimale Darstellung hhhh.

  • Für die x-Konvertierung werden die Buchstaben abcdef verwendet.
  • Für die X-Konvertierung werden die Buchstaben ABCDEF verwendet.
  • Genauigkeit gibt die Mindestanzahl von Ziffern an, die erscheinen sollen. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, führt die Konvertierung zu keinen Zeichen.
  • In der alternativen Implementierung 0x wird 0X dem Ergebnis vorangestellt, wenn der konvertierte Wert ungleich Null ist.
N/A
u

Konvertiert eine vorzeichenlose ganze Zahl in eine Dezimaldarstellung dddd.

  • Genauigkeit gibt die Mindestanzahl von Ziffern an, die erscheinen sollen.
  • Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, führt die Konvertierung zu keinen Zeichen.
N/A
f
F (C99)

Konvertiert eine Gleitkommazahl in die Dezimalnotation im Stil [-]ddd.ddd.

  • Genauigkeit gibt die genaue Anzahl von Ziffern an, die nach dem Dezimalpunktzeichen erscheinen sollen.
  • Die Standardgenauigkeit ist 6.
  • In der alternativen Implementierung wird das Dezimalpunktzeichen auch dann geschrieben, wenn keine Ziffern folgen.
  • Für den Konvertierungsstil von Unendlich und NaN siehe Anmerkungen.
N/A N/A
double
double (C99)
N/A N/A N/A N/A
long double
e
E

Konvertiert eine Gleitkommazahl in die dezimale Exponentennotation.

  • Für den e-Konvertierungsstil wird [-]d.ddd e±dd verwendet.
  • Für den E-Konvertierungsstil wird [-]d.ddd E±dd verwendet.
  • Der Exponent enthält mindestens zwei Ziffern, weitere Ziffern werden nur bei Bedarf verwendet.
  • Wenn der Wert 0 ist, ist der Exponent ebenfalls 0.
  • Genauigkeit gibt die genaue Anzahl von Ziffern an, die nach dem Dezimalpunktzeichen erscheinen sollen.
  • Die Standardgenauigkeit ist 6.
  • In der alternativen Implementierung wird das Dezimalpunktzeichen auch dann geschrieben, wenn keine Ziffern folgen.
  • Für den Konvertierungsstil von Unendlich und NaN siehe Anmerkungen.
N/A N/A N/A N/A N/A N/A
a
A

(C99)

Konvertiert eine Gleitkommazahl in die hexadezimale Exponentennotation.

  • Für den a-Konvertierungsstil wird [-] 0xh.hhh p±d verwendet.
  • Für den A-Konvertierungsstil wird [-] 0Xh.hhh P±d verwendet.
  • Die erste hexadezimale Ziffer ist nicht 0, wenn das Argument ein normalisierter Gleitkommawert ist.
  • Wenn der Wert 0 ist, ist der Exponent ebenfalls 0.
  • Genauigkeit gibt die genaue Anzahl von Ziffern an, die nach dem hexadezimalen Punktzeichen erscheinen sollen.
  • Die Standardgenauigkeit ist ausreichend für die exakte Darstellung des Werts.
  • In der alternativen Implementierung wird das Dezimalpunktzeichen auch dann geschrieben, wenn keine Ziffern folgen.
  • Für den Konvertierungsstil von Unendlich und NaN siehe Anmerkungen.
N/A N/A N/A N/A N/A N/A
g
G

Konvertiert eine Gleitkommazahl in eine dezimale oder dezimale Exponentennotation, abhängig vom Wert und der Genauigkeit.

  • Für den g-Konvertierungsstil wird eine Konvertierung mit Stil e oder f durchgeführt.
  • Für den G-Konvertierungsstil wird eine Konvertierung mit Stil E oder f(bis C99)F(seit C99) durchgeführt.
  • Sei P gleich der Genauigkeit, wenn sie ungleich Null ist, 6 wenn die Genauigkeit nicht angegeben ist, oder 1 wenn die Genauigkeit 0 ist. Wenn dann eine Konvertierung mit Stil E einen Exponenten von X hätte:
    • Wenn P > X ≥ −4, wird die Konvertierung mit Stil f oder F(seit C99) und Genauigkeit P − 1 − X durchgeführt.
    • Andernfalls wird die Konvertierung mit Stil e oder E und Genauigkeit P − 1 durchgeführt.
  • Sofern keine alternative Darstellung angefordert wird, werden die nachgestellten Nullen entfernt, und das Dezimalpunktzeichen wird ebenfalls entfernt, wenn kein Bruchteil übrig bleibt.
  • Für den Konvertierungsstil von Unendlich und NaN siehe Anmerkungen.
N/A N/A N/A N/A N/A N/A
n

Gibt die Anzahl der bisher geschriebenen Zeichen durch diesen Aufruf der Funktion zurück.

  • Das Ergebnis wird geschrieben in den Wert, auf den das Argument zeigt.
  • Die Spezifikation darf keine Flag, Feldbreite oder Genauigkeit enthalten.
  • Für den z-Modifikator ist der erwartete Argumenttyp S*, wobei S die vorzeichenbehaftete Version von size_t ist.
signed char*
short*
int*
long*
long long*
intmax_t*
※
 ptrdiff_t* 
N/A
p

Schreibt eine implementierungsdefinierte Zeichensequenz, die einen Zeiger definiert.

N/A N/A
void*
N/A N/A N/A N/A N/A N/A
Anmerkungen

Die Gleitkomma-Konvertierungsfunktionen konvertieren Unendlich in inf oder infinity. Welche verwendet wird, ist implementierungsdefiniert.

NaN (Not-a-Number) wird in nan oder nan(char_sequence) konvertiert. Welche verwendet wird, ist implementierungsdefiniert.

Die Konvertierungen F, E, G, A geben stattdessen INF, INFINITY, NAN aus.

Der Konvertierungsspezifizierer, der zum Drucken von char, unsigned char, signed char, short und unsigned short verwendet wird, erwartet die beförderten Typen der Standardargument-Beförderungen, aber vor dem Drucken wird sein Wert in char, unsigned char, signed char, short und unsigned short konvertiert. Es ist sicher, Werte dieser Typen zu übergeben, da die Beförderung beim Aufruf einer variadischen Funktion stattfindet.

Die korrekten Konvertierungsspezifikationen für die ganzzahligen Typen fester Breite (int8_t, usw.) sind im Header <inttypes.h> definiert (obwohl PRIdMAX, PRIuMAX, usw. synonym mit %jd, %ju, usw. ist).

Der speicher-schreibende Konvertierungsspezifizierer %n ist ein häufiges Ziel von Sicherheitsangriffen, bei denen Formatstrings von Benutzereingaben abhängen und wird von der Familie der geprüften printf_s-Funktionen nicht unterstützt(seit C11).

Es gibt einen Sequenzpunkt nach der Aktion jedes Konvertierungsspezifizierers; dies ermöglicht das Speichern mehrerer %n-Ergebnisse in derselben Variable oder, als Grenzfall, das Drucken einer Zeichenkette, die durch ein früheres %n innerhalb desselben Aufrufs modifiziert wurde.

Wenn eine Konvertierungsspezifikation ungültig ist, ist das Verhalten undefiniert.

Rückgabewert

1-3) Die Anzahl der geschriebenen Zeichen bei Erfolg oder ein negativer Wert bei einem Fehler.
4) Die Anzahl der geschriebenen Zeichen bei Erfolg oder ein negativer Wert bei einem Fehler. Wenn die resultierende Zeichenkette aufgrund des buf_size-Limits abgeschnitten wird, gibt die Funktion die Gesamtzahl der Zeichen (ohne das abschließende Nullbyte) zurück, die geschrieben worden wären, wenn das Limit nicht auferlegt worden wäre.
5,6) Anzahl der Zeichen, die an den Ausgabestrom übertragen wurden, oder ein negativer Wert, wenn ein Ausgabefehler, ein Verstoß gegen die Laufzeitbeschränkungen oder ein Kodierungsfehler aufgetreten ist.
7) Anzahl der Zeichen, die in buffer geschrieben wurden, ohne das Nullzeichen (das immer geschrieben wird, solange buffer kein Nullzeiger ist und bufsz nicht Null und nicht größer als RSIZE_MAX ist), oder Null bei Verstößen gegen Laufzeitbeschränkungen, und ein negativer Wert bei Kodierungsfehlern.
8) Anzahl der Zeichen ohne das abschließende Nullzeichen (das immer geschrieben wird, solange buffer kein Nullzeiger ist und bufsz nicht Null und nicht größer als RSIZE_MAX ist), die in buffer geschrieben worden wären, wenn bufsz ignoriert worden wäre, oder ein negativer Wert, wenn ein Verstoß gegen Laufzeitbeschränkungen oder ein Kodierungsfehler aufgetreten ist.

Anmerkungen

Alle diese Funktionen rufen va_arg mindestens einmal auf, der Wert von arg ist nach der Rückgabe unbestimmt. Diese Funktionen rufen va_end nicht auf, dies muss vom Aufrufer erfolgen.

vsnprintf_s, im Gegensatz zu vsprintf_s, wird das Ergebnis abschneiden, damit es in das Array passt, auf das buffer zeigt.

Die Implementierung von vsnprintf_s in der Microsoft CRT entspricht nicht dem C-Standard. Die Microsoft-Version hat einen zusätzlichen Parameter size_t count an dritter Stelle, der die maximale Anzahl der zu schreibenden Zeichen enthält, ohne den Nullterminator. Dieser Parameter unterscheidet sich möglicherweise von der Puffergröße, die durch den Parameter size_t bufsz bereitgestellt wird.

Beispiel

#include <stdarg.h>
#include <stdio.h>
#include <time.h>

void debug_log(const char* fmt, ...)
{
    struct timespec ts;
    timespec_get(&ts, TIME_UTC);
    char time_buf[100];
    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);

    va_list args1;
    va_start(args1, fmt);
    va_list args2;
    va_copy(args2, args1);
    char buf[1+vsnprintf(NULL, 0, fmt, args1)];
    va_end(args1);
    vsnprintf(buf, sizeof buf, fmt, args2);
    va_end(args2);

    printf("%s [debug]: %s\n", time_buf, buf);
}

int main(void)
{
    debug_log("Logging, %d, %d, %d", 1, 2, 3);
}

Mögliche Ausgabe:

02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3

Referenzen

  • C23-Standard (ISO/IEC 9899:2024):
  • 7.21.6.8 Die vfprintf-Funktion (S. TBD)
  • 7.21.6.10 Die vprintf-Funktion (S. TBD)
  • 7.21.6.12 Die vsnprintf-Funktion (S. TBD)
  • 7.21.6.13 Die vsprintf-Funktion (S. TBD)
  • K.3.5.3.8 Die vfprintf_s-Funktion (S. TBD)
  • K.3.5.3.10 Die vprintf_s-Funktion (S. TBD)
  • K.3.5.3.12 Die vsnprintf_s-Funktion (S. TBD)
  • K.3.5.3.13 Die vsprintf_s-Funktion (S. TBD)
  • C17-Standard (ISO/IEC 9899:2018):
  • 7.21.6.8 Die vfprintf-Funktion (S. 238)
  • 7.21.6.10 Die vprintf-Funktion (S. 239)
  • 7.21.6.12 Die vsnprintf-Funktion (S. 239-240)
  • 7.21.6.13 Die vsprintf-Funktion (S. 240)
  • K.3.5.3.8 Die vfprintf_s-Funktion (S. 434)
  • K.3.5.3.10 Die vprintf_s-Funktion (S. 435)
  • K.3.5.3.12 Die vsnprintf_s-Funktion (S. 436-437)
  • K.3.5.3.13 Die vsprintf_s-Funktion (S. 437)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.21.6.8 Die vfprintf-Funktion (S. 326-327)
  • 7.21.6.10 Die vprintf-Funktion (S. 328)
  • 7.21.6.12 Die vsnprintf-Funktion (S. 329)
  • 7.21.6.13 Die vsprintf-Funktion (S. 329)
  • K.3.5.3.8 Die vfprintf_s-Funktion (S. 597)
  • K.3.5.3.10 Die vprintf_s-Funktion (S. 598-599)
  • K.3.5.3.12 Die vsnprintf_s-Funktion (S. 600)
  • K.3.5.3.13 Die vsprintf_s-Funktion (S. 601)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.19.6.8 Die vfprintf-Funktion (S. 292)
  • 7.19.6.10 Die vprintf-Funktion (S. 293)
  • 7.19.6.12 Die vsnprintf-Funktion (S. 294)
  • 7.19.6.13 Die vsprintf-Funktion (S. 295)
  • C89/C90-Standard (ISO/IEC 9899:1990):
  • 4.9.6.7 Die vfprintf-Funktion
  • 4.9.6.8 Die vprintf-Funktion
  • 4.9.6.9 Die vsprintf-Funktion

Siehe auch

druckt formatierte Breitzeichen-Ausgabe nach stdout, einen Dateistrom
oder einen Puffer unter Verwendung einer variablen Argumentliste
(Funktion)
druckt formatierte Ausgabe nach stdout, einen Dateistrom oder einen Puffer
(Funktion)
liest formatierte Eingabe von stdin, einem Dateistrom oder einem Puffer
unter Verwendung einer variablen Argumentliste
(Funktion)
C++-Dokumentation für vprintf, vfprintf, vsprintf, vsnprintf