Namespaces
Variants

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

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
vprintf vfprintf vsprintf vsnprintf vprintf_s vfprintf_s vsprintf_s vsnprintf_s
(C99) (C11) (C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
Definiert in Header <stdio.h>
(1)
int vprintf ( const char * format, va_list vlist ) ;
(bis C99)
int vprintf ( const char * restrict format, va_list vlist ) ;
(seit C99)
(2)
int vfprintf ( FILE * stream, const char * format, va_list vlist ) ;
(bis C99)
int vfprintf ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(seit C99)
(3)
int vsprintf ( char * buffer, const char * format, va_list vlist ) ;
(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 definierten Speicherorten, konvertiert sie in entsprechende Zeichenketten und schreibt die Ergebnisse in verschiedene Senken.

1) Schreibt die Ergebnisse in stdout .
2) Schreibt die Ergebnisse in einen Dateistrom stream .
3) Schreibt die Ergebnisse in einen Zeichenketten- buffer .
4) Schreibt die Ergebnisse in einen Zeichenstring buffer . Höchstens bufsz - 1 Zeichen werden geschrieben. Der resultierende Zeichenstring wird mit einem Nullzeichen abgeschlossen, es sei denn bufsz ist null. Wenn bufsz null ist, wird nichts geschrieben und buffer kann ein Nullzeiger sein, jedoch wird der Rückgabewert (Anzahl der Bytes, die ohne den Nullterminator geschrieben würden) weiterhin berechnet und zurückgegeben.
5-8) Gleich wie (1-4) , mit der Ausnahme, dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler -Funktion aufrufen:
  • das Konvertierungsspezifizierer %n ist in format vorhanden
  • eines der Argumente, die %s entsprechen, ist ein Nullzeiger
  • format oder buffer ist ein Nullzeiger
  • bufsz ist null oder größer als RSIZE_MAX
  • Kodierungsfehler in einem der String- und Zeichenkonvertierungsspezifizierer auftreten
  • (nur für vsprintf_s ), der in buffer zu speichernde String (einschließlich des abschließenden Nullzeichens) würde bufsz überschreiten
Wie bei allen grenzprüfenden Funktionen sind vprintf_s , vfprintf_s , vsprintf_s und vsnprintf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 definiert, bevor <stdio.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

stream - Ausgabedateistream, in den geschrieben wird
buffer - Zeiger auf einen Zeichenstring, in den geschrieben wird
bufsz - bis zu bufsz - 1 Zeichen können geschrieben werden, plus den Nullterminator
format - Zeiger auf einen nullterminierten Zeichenstring, der angibt, wie die Daten zu interpretieren sind
vlist - variable Argumentenliste, die die auszugebenden Daten enthält

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

  • Einleitendes % Zeichen.
  • (optional) ein oder mehrere Flags, die das Verhalten der Konvertierung modifizieren:
  • - : das Ergebnis der Konvertierung wird innerhalb des Feldes linksbündig ausgerichtet (standardmäßig ist es rechtsbündig).
  • + : das Vorzeichen von vorzeichenbehafteten Konvertierungen wird immer dem Ergebnis vorangestellt (standardmäßig wird das Ergebnis nur dann mit einem Minus versehen, wenn es negativ ist).
  • space : wenn das Ergebnis einer vorzeichenbehafteten Konvertierung nicht mit einem Vorzeichen beginnt oder leer ist, wird dem Ergebnis ein Leerzeichen vorangestellt. Wird ignoriert, wenn das + -Flag vorhanden ist.
  • # : alternative Form der Konvertierung wird durchgeführt. Siehe die nachfolgende Tabelle für genaue Auswirkungen, andernfalls ist das Verhalten undefiniert.
  • 0 : für Ganzzahl- und Gleitkommazahl-Konvertierungen werden führende Nullen zum Auffüllen des Feldes verwendet anstelle von space -Zeichen. Für Ganzzahlen wird es ignoriert, wenn die Genauigkeit explizit angegeben ist. Für andere Konvertierungen führt die Verwendung dieses Flags zu undefiniertem Verhalten. Wird ignoriert, wenn das - -Flag vorhanden ist.
  • (optional) Ganzzahlwert oder * , der die minimale Feldbreite angibt. Das Ergebnis wird bei Bedarf auf der linken Seite (bei rechtsbündiger Ausrichtung) oder auf der rechten Seite (bei linksbündiger Ausrichtung) mit Leerzeichen aufgefüllt (standardmäßig). Falls * verwendet wird, wird die Breite durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument und dem die Genauigkeit liefernden Argument (falls vorhanden) erscheint. Wenn der Wert des Arguments negativ ist, führt dies zur Angabe des - -Flags und einer positiven Feldbreite (Hinweis: Dies ist die minimale Breite: Der Wert wird niemals abgeschnitten.).
  • (optional) . gefolgt von einer Ganzzahl oder * , oder keines von beiden, was die Präzision der Konvertierung spezifiziert. Falls * verwendet wird, wird die Präzision durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument erscheint, aber nach dem Argument, das die minimale Feldbreite liefert, falls eines angegeben wurde. Wenn der Wert dieses Arguments negativ ist, wird er ignoriert. Wenn weder eine Zahl noch * verwendet wird, wird die Präzision als Null angenommen. Siehe die nachfolgende Tabelle für die genauen Auswirkungen der Präzision .
  • (optional) Längenmodifikator der die Größe des Arguments spezifiziert (in Kombination mit dem Konvertierungsformat-Spezifizierer bestimmt er den Typ des entsprechenden Arguments).
  • Konvertierungsformat-Spezifizierer.

Die folgenden Formatbezeichner sind verfügbar:

Konvertierungsspezifizierer Erklärung Erwarteter
Argumenttyp
Längenmodifikator→ hh h keine l ll j z t L
Nur verfügbar seit C99→ Ja Ja Ja Ja Ja
% Schreibt ein literales % . Die vollständige Konvertierungsspezifikation muss %% lauten. 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 durch %ls mit einem wchar_t [ 2 ] -Argument.
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

Schreibt einen Zeichenstring .

  • Das Argument muss ein Zeiger auf das erste Element eines Zeichenarrays sein.
  • Präzision gibt die maximale Anzahl zu schreibender Bytes an. Wenn Präzision nicht angegeben ist, werden alle Bytes bis zum ersten Nullterminator (ausschließlich) geschrieben.
  • Wenn der l -Spezifizierer verwendet wird, muss das Argument ein Zeiger auf das erste Element eines Arrays von wchar_t sein, das wie durch einen Aufruf von wcrtomb mit einem nullinitialisierten Konvertierungszustand in ein char-Array konvertiert wird.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

Wandelt eine vorzeichenbehaftete Ganzzahl in die Dezimaldarstellung [-]dddd um.

  • Präzision gibt die Mindestanzahl der anzuzeigenden Ziffern an. Die Standardpräzision ist 1 .
  • Wenn sowohl der konvertierte Wert als auch die Präzision ​ 0 ​ sind, ergibt die Konvertierung keine Zeichen.
  • Für den z -Modifikator ist der erwartete Argumenttyp die vorzeichenbehaftete Version von size_t .
signed char
short
int
long
long long
※
N/A
o

Wandelt eine vorzeichenlose Ganzzahl in die Oktaldarstellung oooo um.

  • Präzision gibt die Mindestanzahl der anzuzeigenden Ziffern an. Die Standardpräzision ist 1 .
  • Wenn sowohl der konvertierte Wert als auch die Präzision ​ 0 ​ sind, ergibt die Konvertierung keine Zeichen.
  • In der alternativen Implementierung wird die Präzision bei Bedarf erhöht, um eine führende Null zu schreiben. In diesem Fall wird, wenn sowohl der konvertierte Wert als auch die Präzision ​ 0 ​ sind, eine einzelne ​ 0 ​ geschrieben.
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
vorzeichenlose Version von ptrdiff_t
N/A
x
X

Wandelt eine vorzeichenlose Ganzzahl in die hexadezimale Darstellung hhhh um.

  • Für die x -Konversion werden die Buchstaben abcdef verwendet.
  • Für die X -Konversion werden die Buchstaben ABCDEF verwendet.
  • Präzision gibt die Mindestanzahl der anzuzeigenden Ziffern an. Die Standardpräzision ist 1 .
  • Wenn sowohl der konvertierte Wert als auch die Präzision ​ 0 ​ sind, ergibt die Konversion keine Zeichen.
  • In der alternativen Implementierung wird 0x oder 0X nichtnull-Werten vorangestellt.
N/A
u

Wandelt eine unsigned integer in die Dezimaldarstellung dddd um.

  • Precision gibt die minimale Anzahl der anzuzeigenden Ziffern an.
  • Die Standard-Präzision ist 1 .
  • Wenn sowohl der konvertierte Wert als auch die Präzision ​ 0 ​ sind, ergibt die Konvertierung keine Zeichen.
N/A
f
F (C99)

Konvertiert eine Gleitkommazahl in die Dezimalschreibweise im Format [-]ddd.ddd .

  • Präzision gibt die exakte Anzahl der Nachkommastellen an.
  • Die Standardpräzision ist 6 .
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch ohne folgende Ziffern geschrieben.
  • Für die Konvertierung von Unendlich und NaN siehe Hinweise .
N/A N/A
double
double (C99)
N/A N/A N/A N/A
long double
e
E

Wandelt eine Gleitkommazahl in die dezimale Exponentenschreibweise um.

  • 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 ​ .
  • Präzision gibt die exakte Anzahl der Ziffern nach dem Dezimaltrennzeichen an.
  • Die Standardpräzision ist 6 .
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern folgen.
  • Für die Konvertierung von Unendlich und NaN siehe Hinweise .
N/A N/A N/A N/A N/A N/A
a
A

(C99)

Wandelt eine Gleitkommazahl in die hexadezimale Exponentenschreibweise um.

  • Für den a -Konvertierungsstil wird [-]  0x h.hhh  p ±d verwendet.
  • Für den A -Konvertierungsstil wird [-]  0X h.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 ​ .
  • Präzision gibt die exakte Anzahl der Ziffern an, die nach dem hexadezimalen Punktzeichen erscheinen sollen.
  • Die Standardpräzision ist ausreichend für die exakte Darstellung des Werts.
  • In der alternativen Implementierung wird das Dezimalpunktzeichen auch dann geschrieben, wenn keine Ziffern darauf folgen.
  • Für die Konvertierung von Unendlich und NaN siehe Hinweise .
N/A N/A N/A N/A N/A N/A
g
G

Wandelt eine Gleitkommazahl in Dezimal- oder Exponentenschreibweise um, abhängig vom Wert und der Genauigkeit .

  • Für den g -Konvertierungsstil wird die Konvertierung mit Stil e oder f durchgeführt.
  • Für den G -Konvertierungsstil wird die Konvertierung mit Stil E oder f (bis C99) F (seit C99) durchgeführt.
  • Sei P gleich der Genauigkeit falls ungleich Null, 6 falls die Genauigkeit nicht angegeben ist, oder 1 falls die Genauigkeit ​ 0 ​ ist. Dann, wenn eine Konvertierung mit Stil E einen Exponenten X hätte:
    • Wenn P > X ≥ −4 , erfolgt die Konvertierung mit Stil f oder F (seit C99) und Genauigkeit P − 1 − X .
    • Andernfalls erfolgt die Konvertierung mit Stil e oder E und Genauigkeit P − 1 .
  • Sofern keine alternative Darstellung angefordert wird, werden nachgestellte Nullen entfernt, ebenso wird das Dezimaltrennzeichen entfernt, wenn kein Nachkommateil verbleibt.
  • Für Konvertierungen von Unendlich und NaN siehe Hinweise .
N/A N/A N/A N/A N/A N/A
n

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

  • Das Ergebnis wird an die durch das Argument gezeigte Adresse geschrieben .
  • Die Spezifikation darf keine Flags , 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 *
※
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
Hinweise

Die Gleitkomma-Konvertierungsfunktionen konvertieren Unendlich zu inf oder infinity . Welches verwendet wird, ist implementierungsdefiniert.

Keine-Zahl wird zu nan oder nan( char_sequence ) konvertiert. Welches verwendet wird, ist implementierungsdefiniert.

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

Der Konvertierungsspezifizierer zum Drucken von char , unsigned char , signed char , short und unsigned short erwartet gepromotete Typen von Default Argument Promotions , aber vor dem Drucken wird sein Wert zu char , unsigned char , signed char , short und unsigned short konvertiert. Es ist sicher, Werte dieser Typen zu übergeben, aufgrund der Promotion, die beim Aufruf einer variadischen Funktion stattfindet.

Die korrekten Konvertierungsspezifizierer für die festbreitigen Zeichentypen ( int8_t usw.) sind im Header <inttypes.h> definiert (obwohl PRIdMAX , PRIuMAX usw. synonym mit %jd , %ju usw. sind).

Der speicher-schreibende Konvertierungsspezifizierer %n ist ein häufiges Ziel von Sicherheitslücken, bei denen Formatstrings von Benutzereingaben abhängen und wird von der bounds-checked printf_s -Funktionsfamilie nicht unterstützt (seit C11) .

Es gibt einen Sequence Point nach der Aktion jedes Konvertierungsspezifizierers; dies erlaubt das Speichern mehrerer %n -Ergebnisse in derselben Variable oder, als Randfall, das Drucken einer Zeichenkette, die durch einen früheren %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 der resultierende String aufgrund des buf_size Limits abgeschnitten wird, gibt die Funktion die Gesamtanzahl der Zeichen (ohne das abschließende Null-Byte) zurück, die geschrieben worden wären, wenn das Limit nicht auferlegt worden wäre.
5,6) Anzahl der an den Ausgabestream übertragenen Zeichen oder ein negativer Wert, falls ein Ausgabefehler, ein Verstoß gegen Laufzeitbeschränkungen oder ein Kodierungsfehler aufgetreten ist.
7) Anzahl der in den buffer geschriebenen Zeichen, ohne das Nullzeichen (welches immer geschrieben wird, solange buffer kein Nullzeiger ist und bufsz nicht null und nicht größer als RSIZE_MAX ist), oder null bei Laufzeitbedingungsverletzungen, und negativer Wert bei Kodierungsfehlern
8) Anzahl der Zeichen ohne das abschließende Nullzeichen (welches 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 bei Verletzung der Laufzeitbedingungen oder einem Kodierungsfehler

Hinweise

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

vsnprintf_s , im Gegensatz zu vsprintf_s , wird das Ergebnis abschneiden, um in das durch buffer zeigende Array zu passen.

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

Beispiel

Diesen Code ausführen 
#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

(C95) (C95) (C95) (C11) (C11) (C11) (C11)
gibt formatierten Breitzeichen-Output an stdout , einen Dateistream
oder einen Puffer unter Verwendung einer variablen Argumentenliste aus
(Funktion)
(C99) (C11) (C11) (C11) (C11)
gibt formatierten Output an stdout , einen Dateistream oder einen Puffer aus
(Funktion)
(C99) (C99) (C99) (C11) (C11) (C11)
liest formatierten Input von stdin , einem Dateistream oder einem Puffer
unter Verwendung einer variablen Argumentenliste
(Funktion)
C++-Dokumentation für vprintf , vfprintf , vsprintf , vsnprintf