Namespaces
Variants

vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s

Von de.cppreference.net
< c | io
 
 
Datei-Ein-/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 <wchar.h>
int vwprintf( const wchar_t* format, va_list vlist );
(1) (seit C95)
(bis C99)
int vwprintf( const wchar_t* restrict format, va_list vlist );
(seit C99)
int vfwprintf( FILE* stream, const wchar_t* format, va_list vlist );
(2) (seit C95)
(bis C99)
int vfwprintf( FILE* restrict stream,
               const wchar_t* restrict format, va_list vlist );
(seit C99)
int vswprintf( wchar_t* buffer, size_t bufsz,
               const wchar_t* format, va_list vlist );
(3) (seit C95)
(bis C99)
int vswprintf( wchar_t* restrict buffer, size_t bufsz,
               const wchar_t* restrict format, va_list vlist );
(seit C99)
int vwprintf_s( const wchar_t* restrict format, va_list vlist);
(4) (seit C11)
int vfwprintf_s( FILE* restrict stream,
                 const wchar_t* restrict format, va_list vlist);
(5) (seit C11)
int vswprintf_s( wchar_t* restrict buffer, rsize_t bufsz,
                 const wchar_t* restrict format, va_list vlist);
(6) (seit C11)
int vsnwprintf_s( wchar_t* restrict buffer, rsize_t bufsz,
                  const wchar_t* restrict format, va_list vlist);
(7) (seit C11)

Lädt die Daten von den durch vlist definierten Speicherorten, konvertiert sie in Breitzeichen-Äquivalente und schreibt die Ergebnisse in verschiedene Ausgabeziele.

1) Schreibt die Ergebnisse auf stdout.
2) Schreibt die Ergebnisse in einen Dateistrom stream.
3) Schreibt die Ergebnisse in einen Breitzeichen-String buffer. Es werden maximal bufsz - 1 Breitzeichen geschrieben, gefolgt von einem abschließenden Null-Breitzeichen. Der resultierende Breitzeichen-String wird mit einem Null-Breitzeichen abgeschlossen, es sei denn, bufsz ist Null.
4-6) Gleich wie (1-3), mit der Ausnahme, dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler-Funktion aufrufen:
  • der 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 / sizeof(wchar_t)
  • Kodierungsfehler treten bei allen Konvertierungsspezifizierern für Zeichenketten und Zeichen auf
  • (nur für vswprintf_s) die Zeichenkette, die in buffer gespeichert werden soll (einschließlich des abschließenden Null-Breitzeichens), würde bufsz überschreiten.
7) Gleich wie (6), mit dem Unterschied, dass das Ergebnis abgeschnitten wird, um in das Array zu passen, auf das buffer zeigt.
Wie bei allen grenzgeprüften Funktionen sind vwprintf_s, vfwprintf_s, vswprintf_s und vsnwprintf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ auf die ganzzahlige Konstante 1 setzt, bevor er <stdio.h> einbindet.

Parameter

stream - Ausgabe-Breitzeichenstrom, in den geschrieben wird
buffer - Zeiger auf einen Breitzeichen-String, in den geschrieben wird
bufsz - maximale Anzahl zu schreibender Breitzeichen
format - Zeiger auf einen nullterminierten Breitzeichen-String, der angibt, wie die Daten zu interpretieren sind
vlist - Liste variabler Argumente, die die zu druckenden Daten enthält.


Der format-String besteht aus gewöhnlichen Breitzeichen (außer %), die unverändert in den Ausgabestrom kopiert werden, sowie Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat das folgende Format:

  • Einleitendes %-Zeichen.
  • (optional) eines 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 Konvertierungsergebnis immer vorangestellt (standardmäßig wird dem Ergebnis nur dann ein Minus vorangestellt, 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. Es wird ignoriert, wenn das +-Flag vorhanden ist.
  • #: Die alternative Form der Konvertierung wird durchgeführt. Siehe Tabelle unten für genaue Auswirkungen, andernfalls ist das Verhalten undefiniert.
  • 0: Bei Ganzzahl- und Gleitkommazahlen-Konvertierungen werden führende Nullen anstelle von space-Zeichen zum Auffüllen des Feldes 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 space-Zeichen aufgefüllt, bei Rechtsbündigkeit links, bei Linksbündigkeit rechts. Wenn * verwendet wird, wird die Breite durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument und dem Argument, das die Genauigkeit angibt (falls vorhanden), erscheint. Wenn der Wert des Arguments negativ ist, ergibt sich daraus das --Flag und eine positive Feldbreite (Hinweis: Dies ist die Mindestbreite. Der Wert wird niemals abgeschnitten.).
  • (optional) . gefolgt von einer Ganzzahl oder *, oder keines von beidem, das die Genauigkeit der Konvertierung angibt. Wenn * verwendet wird, wird die Genauigkeit durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument, aber nach dem Argument erscheint, das die minimale Feldbreite angibt (falls vorhanden). Wenn der Wert dieses Arguments negativ ist, wird er ignoriert. Wenn weder eine Zahl noch * verwendet wird, wird die Genauigkeit als Null angenommen. Siehe Tabelle unten für die genauen Auswirkungen der Genauigkeit.
  • (optional) Längenmodifikator, der die Größe des Arguments angibt (in Kombination mit dem Konvertierungsformat-Spezifizierer gibt er den Typ des entsprechenden Arguments an).
  • Konvertierungsformat-Spezifizierer.

Die folgenden Format-Spezifizierer sind verfügbar:

Konvertierungs-
Spezifizierer
Erklärung Erwarteter
Argumenttyp
Längenmodifikator→ hh h none l ll j z t L
Nur seit C99 verfügbar→ Ja Ja Ja Ja Ja
% Schreibt literales %. 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 wchar_t konvertiert, als ob btowc aufgerufen würde.
  • Wenn der l-Modifikator verwendet wird, wird das wint_t-Argument zuerst in wchar_t konvertiert.
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

Schreibt einen Zeichen-String.

  • Das Argument muss ein Zeiger auf das erste Element eines Zeichenarrays sein, das eine Multibyte-Zeichensequenz enthält, die im anfänglichen Schaltzustand beginnt, welche durch einen Aufruf von mbrtowc mit initialisiertem Konvertierungszustand in ein Breitzeichen-Array konvertiert wird.
  • Genauigkeit gibt die maximale Anzahl der zu schreibenden Breitzeichen an. Wenn Genauigkeit nicht angegeben ist, werden alle Breitzeichen bis einschließlich des ersten Null-Abschlusszeichens geschrieben.
  • Wenn der l-Spezifizierer verwendet wird, muss das Argument ein Zeiger auf das erste Element eines Arrays von wchar_t sein.
N/A N/A
char*
wchar_t*
N/A N/A N/A N/A N/A
d
i

Konvertiert eine vorzeichenbehaftete Ganzzahl in eine Dezimaldarstellung [-]dddd.

  • Genauigkeit gibt die minimale Anzahl der anzuzeigenden Ziffern an. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 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
intmax_t
※
ptrdiff_t
N/A
b
B (optional)

(C23)

Konvertiert eine vorzeichenlose Ganzzahl in eine binäre Darstellung bbbb.

  • Genauigkeit gibt die minimale Anzahl der anzuzeigenden Ziffern an. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, ergibt die Konvertierung keine Zeichen.
  • In der alternativen Implementierung wird 0b oder 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 Ganzzahl in eine oktale Darstellung oooo.

  • Genauigkeit gibt die minimale Anzahl der anzuzeigenden Ziffern an. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, ergibt die Konvertierung keine Zeichen.
  • In der alternativen Implementierung wird die Genauigkeit bei Bedarf erhöht, um eine führende Null zu schreiben. In diesem Fall, wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, wird eine einzelne 0 geschrieben.
N/A
x
X

Konvertiert eine vorzeichenlose Ganzzahl 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 minimale Anzahl der anzuzeigenden Ziffern an. Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, ergibt die Konvertierung keine Zeichen.
  • In der alternativen Implementierung wird 0x oder 0X dem Ergebnis vorangestellt, wenn der konvertierte Wert ungleich Null ist.
N/A
u

Konvertiert eine vorzeichenlose Ganzzahl in eine dezimale Darstellung dddd.

  • Genauigkeit gibt die minimale Anzahl der anzuzeigenden Ziffern an.
  • Die Standardgenauigkeit ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, ergibt die Konvertierung keine Zeichen.
N/A
f
F (C99)

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

  • Genauigkeit gibt die genaue Anzahl der nach dem Dezimaltrennzeichen erscheinenden Ziffern an.
  • Die Standardgenauigkeit ist 6.
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern darauf folgen.
  • Für die Konvertierung 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 Exponentenschreibweise.

  • 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 der nach dem Dezimaltrennzeichen erscheinenden Ziffern an.
  • Die Standardgenauigkeit ist 6.
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern darauf folgen.
  • Für die Konvertierung 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 Exponentenschreibweise.

  • 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 der nach dem hexadezimalen Trennzeichen erscheinenden Ziffern an.
  • Die Standardgenauigkeit ist für die exakte Darstellung des Wertes ausreichend.
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern darauf folgen.
  • Für die Konvertierung 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 Dezimal- oder Dezimalexponentenschreibweise, 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 ungleich Null, 6 wenn die Genauigkeit nicht angegeben ist, oder 1 wenn die Genauigkeit 0 ist. Dann, wenn eine Konvertierung mit Stil E einen Exponenten von 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 die nachgestellten Nullen entfernt, ebenso wird das Dezimaltrennzeichen entfernt, wenn kein Bruchteil übrig bleibt.
  • Für die Konvertierung von Unendlich und NaN siehe Anmerkungen.
N/A N/A N/A N/A N/A N/A
n

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

  • Das Ergebnis wird geschrieben in den Wert, auf den das Argument zeigt.
  • Die Spezifikation darf kein Flag, keine Feldbreite und keine 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. Welches verwendet wird, ist implementierungsdefiniert.

NaN wird in 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, der zum Drucken von char, unsigned char, signed char, short und unsigned short verwendet wird, erwartet hochgestufte Typen der Standard-Argument-Hochstufungen, 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 Hochstufung stattfindet, wenn eine variadische Funktion aufgerufen wird.

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

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

Es gibt einen Sequenzpunkt nach der Aktion jedes Konvertierungsspezifizierers; dies erlaubt das Speichern mehrerer %n-Ergebnisse in derselben Variable oder, als Randfall, 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,4) Die Anzahl der geschriebenen Breitzeichen bei Erfolg oder ein negativer Wert, wenn ein Fehler aufgetreten ist.
3) Die Anzahl der geschriebenen Breitzeichen bei Erfolg oder ein negativer Wert, wenn ein Fehler aufgetreten ist. Wenn der resultierende String aufgrund der bufsz-Begrenzung abgeschnitten wird, gibt die Funktion die Gesamtzahl der Zeichen zurück (ohne das abschließende Null-Breitzeichen), die geschrieben worden wären, wenn die Begrenzung nicht bestünde.
2,5) Anzahl der an den Ausgabestrom übertragenen Breitzeichen oder ein negativer Wert, wenn ein Ausgabefehler, ein Verstoß gegen Laufzeitbeschränkungen oder ein Kodierungsfehler aufgetreten ist.
6) Anzahl der in buffer geschriebenen Breitzeichen (ohne das abschließende Null-Breitzeichen, das immer geschrieben wird, solange buffer kein Nullzeiger ist und bufsz nicht Null und nicht größer als RSIZE_MAX/sizeof(wchar_t) ist), oder Null bei Verstößen gegen Laufzeitbeschränkungen und ein negativer Wert bei Kodierungsfehlern.
7) Anzahl der Breitzeichen 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/sizeof(wchar_t) 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 erledigt werden.

Während schmale Zeichenketten vsnprintf bereitstellen, das die Bestimmung der erforderlichen Ausgabepuffergröße ermöglicht, gibt es kein Äquivalent für Breitzeichenketten (bis C11's vsnwprintf_s), und um die Puffergröße zu bestimmen, muss das Programm möglicherweise vswprintf aufrufen, den Rückgabewert überprüfen und einen größeren Puffer neu zuweisen, bis es erfolgreich ist.

vsnwprintf_sim Gegensatz zu vswprintf_s das Ergebnis abschneiden, damit es in das durch buffer angegebene Array passt, obwohl das Abschneiden von den meisten grenzgeprüften Funktionen als Fehler behandelt wird.

Beispiel

#include <locale.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>
#include <time.h>
#include <wchar.h>

void debug_wlog(const wchar_t* 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 args;
    va_start(args, fmt);
    wchar_t buf[1024];
    int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args);
    va_end(args);

    if (rc2 > 0)
       wprintf(L"%s [debug]: %ls\n", time_buf, buf);
    else
       wprintf(L"%s [debug]: (string too long)\n", time_buf);
}

int main(void)
{
    setlocale(LC_ALL, "");
    debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3);
}

Mögliche Ausgabe:

02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3

Referenzen

  • C23-Standard (ISO/IEC 9899:2024):
  • 7.29.2.5 Die Funktion vfwprintf (S.: TBD)
  • 7.29.2.7 Die Funktion vswprintf (S.: TBD)
  • 7.29.2.9 Die Funktion vwprintf (S.: TBD)
  • K.3.9.1.6 Die Funktion vfwprintf_s (S.: TBD)
  • K.3.9.1.8 Die Funktion vsnwprintf_s (S.: TBD)
  • K.3.9.1.9 Die Funktion vswprintf_s (S.: TBD)
  • K.3.9.1.11 Die Funktion vwprintf_s (S.: TBD)
  • C17-Standard (ISO/IEC 9899:2018):
  • 7.29.2.5 Die Funktion vfwprintf (S.: TBD)
  • 7.29.2.7 Die Funktion vswprintf (S.: TBD)
  • 7.29.2.9 Die Funktion vwprintf (S.: TBD)
  • K.3.9.1.6 Die Funktion vfwprintf_s (S.: TBD)
  • K.3.9.1.8 Die Funktion vsnwprintf_s (S.: TBD)
  • K.3.9.1.9 Die Funktion vswprintf_s (S.: TBD)
  • K.3.9.1.11 Die Funktion vwprintf_s (S.: TBD)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.29.2.5 Die Funktion vfwprintf (S.: 417-418)
  • 7.29.2.7 Die Funktion vswprintf (S.: 419)
  • 7.29.2.9 Die Funktion vwprintf (S.: 420)
  • K.3.9.1.6 Die Funktion vfwprintf_s (S.: 632)
  • K.3.9.1.8 Die Funktion vsnwprintf_s (S.: 633-634)
  • K.3.9.1.9 Die Funktion vswprintf_s (S.: 634-635)
  • K.3.9.1.11 Die Funktion vwprintf_s (S.: 636)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.24.2.5 Die Funktion vfwprintf (S.: 363)
  • 7.24.2.7 Die Funktion vswprintf (S.: 364)
  • 7.24.2.9 Die Funktion vwprintf (S.: 365)

Siehe auch

gibt formatierte Ausgabe auf stdout, einen Dateistrom oder einen Puffer aus
unter Verwendung einer variablen Argumentliste
(Funktion)
gibt formatierte Breitzeichen-Ausgabe auf stdout, einen Dateistrom oder einen Puffer aus
(Funktion)
C++-Dokumentation für vwprintf, vfwprintf, vswprintf