Namensräume
Varianten
Aktionen

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

Von cppreference.com
< c‎ | io
 
 
Datei-Ein-/Ausgabe
Typen und Objekte
        
Funktionen
Datei-Zugriff
(C95)
Unformatierte Ein-/Ausgabe
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)

Formatierte Eingabe
Direkte Ein-/Ausgabe
Formatierte Ausgabe
vwprintfvfwprintfvswprintfvwprintf_svfwprintf_svswprintf_svsnwprintf_s
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
Dateipositionierung
Fehlerbehandlung
Operationen auf Dateien
 
Definiert in Header <wchar.h>
(1)
int vwprintf( const wchar_t* format, va_list vlist );
(seit C95)
(bis C99)
int vwprintf( const wchar_t* restrict format, va_list vlist );
(seit C99)
(2)
int vfwprintf( FILE* stream, const wchar_t* format, va_list vlist );
(seit C95)
(bis C99)
int vfwprintf( FILE* restrict stream,
               const wchar_t* restrict format, va_list vlist );
(seit C99)
(3)
int vswprintf( wchar_t* buffer, size_t bufsz,
               const wchar_t* format, va_list vlist );
(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 Daten aus den durch vlist definierten Speicherorten, konvertiert sie in die entsprechenden Wide-String-Äquivalente und schreibt die Ergebnisse in verschiedene Ziele.

1) Schreibt die Ergebnisse nach stdout.
2) Schreibt die Ergebnisse in den Dateistream stream.
3) Schreibt die Ergebnisse in den Wide-String buffer. Maximal bufsz - 1 Wide-Zeichen werden gefolgt von einem Null-Wide-Zeichen geschrieben. Der resultierende Wide-Zeichen-String wird mit einem Null-Wide-Zeichen terminiert, es sei denn, bufsz ist Null.
4-6) Ähnlich 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 im format vorhanden ist
  • eines der Argumente, die %s entsprechen, ein Nullzeiger ist
  • format oder buffer ein Nullzeiger ist
  • bufsz Null oder größer als RSIZE_MAX / sizeof(wchar_t) ist
  • bei der Konvertierung von Zeichenketten und Zeichenspezifizierern Kodierungsfehler auftreten
  • (nur für vswprintf_s) die Zeichenkette, die in buffer gespeichert werden soll (einschließlich des abschließenden Null-Wide-Zeichens) bufsz überschreiten würde.
7) Ähnlich wie (6), mit der Ausnahme, dass das Ergebnis gekürzt wird, um in das von buffer zeigende Array zu passen.
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 wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <stdio.h> auf die Ganzzahlkonstante 1 setzt.

Inhalt

[edit] Parameter

stream - Ausgabe-Wide-Stream, in den geschrieben werden soll
buffer - Zeiger auf eine Wide-Zeichenkette, in die geschrieben werden soll
bufsz - maximale Anzahl von zu schreibenden Wide-Zeichen
format - Zeiger auf eine nullterminierte Wide-Zeichenkette, die angibt, wie die Daten zu interpretieren sind
vlist - Variablenargumentenliste, die die zu druckenden Daten enthält.


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

  • ein einführendes %-Zeichen.
  • (optional) ein oder mehrere Flags, die das Verhalten der Konversion modifizieren
  • -: Das Ergebnis der Konversion wird im Feld linksbündig ausgerichtet (standardmäßig rechtsbündig).
  • +: Das Vorzeichen von Vorzeichenkonversionen wird immer dem Ergebnis der Konversion vorangestellt (standardmäßig wird dem Ergebnis nur dann ein Minus vorangestellt, wenn es negativ ist).
  • Leerzeichen: Wenn das Ergebnis einer Vorzeichenkonversion nicht mit einem Vorzeichen beginnt oder leer ist, wird dem Ergebnis ein Leerzeichen vorangestellt. Es wird ignoriert, wenn das Flag + vorhanden ist.
  • #: Eine alternative Form der Konversion wird durchgeführt. Die genauen Effekte sind in der untenstehenden Tabelle aufgeführt, andernfalls ist das Verhalten undefiniert.
  • 0: Bei Ganzzahl- und Gleitkommazahlenkonversionen werden die Felder mit Nullen aufgefüllt anstelle von Leerzeichen. Bei Ganzzahlen wird dies ignoriert, wenn die Genauigkeit explizit angegeben ist. Bei anderen Konversionen 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 mit Leerzeichen (standardmäßig) aufgefüllt, falls erforderlich, links bei rechtsbündiger Ausrichtung oder rechts bei linksbündiger Ausrichtung. Wenn * verwendet wird, wird die Breite durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument und dem Argument für die Präzision (falls vorhanden) steht. 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 nie gekürzt).
  • (optional) . gefolgt von einer Ganzzahl oder *, oder weder noch, das die Präzision der Konvertierung angibt. Wenn * verwendet wird, wird die Präzision durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument steht, aber nach dem Argument für die minimale Feldbreite (falls vorhanden). Wenn der Wert dieses Arguments negativ ist, wird es ignoriert. Wenn weder eine Zahl noch * verwendet wird, wird die Präzision als Null angenommen. Die genauen Auswirkungen der Präzision finden Sie in der folgenden Tabelle.
  • (optional) Ein Längenmodifikator, der die Größe des Arguments angibt (in Kombination mit dem Konversionsformat-Spezifizierer gibt er den Typ des entsprechenden Arguments an).
  • Ein Konversionsformat-Spezifizierer.

Die folgenden Format-Spezifizierer sind verfügbar:

Konversion
Spezifizierer
Erklärung Erwartet
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 Konversionsspezifikation 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 zunächst in wchar_t konvertiert, als ob durch Aufrufen von btowc.
  • 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 eine Zeichenkette.

  • Das Argument muss ein Zeiger auf das erste Element eines Zeichenarrays sein, das eine Multibyte-Zeichensequenz enthält, die im initialen Shift-Zustand beginnt und in ein Wide-Zeichenarray konvertiert wird, als ob durch einen Aufruf von mbrtowc mit einem mit Null initialisierten Konvertierungszustand.
  • Präzision gibt die maximale Anzahl von zu schreibenden Wide-Zeichen an. Wenn Präzision nicht angegeben ist, werden alle Wide-Zeichen bis zum ersten Nullterminator, diesen aber nicht einschließend, 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 die Dezimaldarstellung [-]dddd.

  • Präzision gibt die minimale Anzahl von Ziffern an, die erscheinen sollen. Die Standardpräzision ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Präzision 0 sind, erzeugt 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

Konvertiert eine vorzeichenlose Ganzzahl in die Oktaldarstellung oooo.

  • Präzision gibt die minimale Anzahl von Ziffern an, die erscheinen sollen. Die Standardpräzision ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Präzision 0 sind, erzeugt 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
vorzeichenbehaftete Version von ptrdiff_t
N/A
x
X

Konvertiert eine vorzeichenlose Ganzzahl in die Hexadezimaldarstellung hhhh.

  • Für die x-Konversionsbuchstaben werden abcdef verwendet.
  • Für die X-Konversionsbuchstaben werden ABCDEF verwendet.
  • Präzision gibt die minimale Anzahl von Ziffern an, die erscheinen sollen. Die Standardpräzision ist 1.
  • Wenn sowohl der konvertierte Wert als auch die Präzision 0 sind, erzeugt die Konvertierung keine Zeichen.
  • In der alternativen Implementierung wird den Ergebnissen 0x oder 0X vorangestellt, wenn der konvertierte Wert ungleich Null ist.
N/A
u

Konvertiert eine vorzeichenlose Ganzzahl in die Dezimaldarstellung dddd.

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

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

  • Genauigkeit gibt die genaue 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 darauf folgen.
  • Informationen zur Konversion von Unendlichkeit und Nicht-Zahl im Hinblick auf den Stil finden Sie unter 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 Dezimal-Exponent-Notation.

  • Für den e-Konversionsstil wird [-]d.ddd e±dd verwendet.
  • Für den E-Konversionsstil wird [-]d.ddd E±dd verwendet.
  • Der Exponent enthält mindestens zwei Ziffern, mehr Ziffern werden nur bei Bedarf verwendet.
  • Wenn der Wert 0 ist, ist auch der Exponent 0.
  • Genauigkeit gibt die genaue 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 darauf folgen.
  • Informationen zur Konversion von Unendlichkeit und Nicht-Zahl im Hinblick auf den Stil finden Sie unter Anmerkungen.
N/A N/A N/A N/A N/A N/A
a
A

(C99)

Konvertiert eine Gleitkommazahl in die Hexadezimal-Exponent-Notation.

  • Für den a-Konversionsstil wird [-] 0xh.hhh p±d verwendet.
  • Für den A-Konversionsstil wird [-] 0Xh.hhh P±d verwendet.
  • Die erste Hexadezimalziffer ist nicht 0, wenn das Argument ein normalisierter Gleitkommawert ist.
  • Wenn der Wert 0 ist, ist auch der Exponent 0.
  • Genauigkeit gibt die exakte Anzahl der Ziffern nach dem Hexadezimaltrennzeichen an.
  • Die Standardgenauigkeit ist ausreichend für die exakte Darstellung des Wertes.
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern darauf folgen.
  • Informationen zur Konversion von Unendlichkeit und Nicht-Zahl im Hinblick auf den Stil finden Sie unter Anmerkungen.
N/A N/A N/A N/A N/A N/A
g
G

Konvertiert eine Gleitkommazahl je nach Wert und Genauigkeit in die Dezimal- oder Dezimal-Exponent-Notation.

  • Für den g-Konversionsstil wird die Konversion mit dem Stil e oder f durchgeführt.
  • Für den G-Konvertierungsstil wird die Konvertierung im Stil E oder f(bis C99)F(seit C99) durchgeführt.
  • Sei P gleich der Präzision, wenn sie ungleich Null ist, 6, wenn die Präzision nicht angegeben ist, oder 1, wenn die Präzision 0 ist. Dann, wenn eine Konvertierung mit dem Stil E einen Exponenten von X hätte
    • Wenn P > X ≥ −4, erfolgt die Konvertierung im Stil f oder F(seit C99) und mit der Präzision P − 1 − X.
    • Andernfalls erfolgt die Konversion im Stil e oder E mit einer Genauigkeit von P − 1.
  • Sofern keine alternative Darstellung angefordert wird, werden nachfolgende Nullen entfernt, und das Dezimaltrennzeichen wird entfernt, wenn kein Bruchteil übrig bleibt.
  • Informationen zur Konversion von Unendlichkeit und Nicht-Zahl im Hinblick auf den Stil finden Sie unter Anmerkungen.
N/A N/A N/A N/A N/A N/A
n

Gibt die bisher von diesem Funktionsaufruf geschriebene Anzahl der Zeichen zurück.

  • Das Ergebnis wird an den Wert geschrieben, auf den das Argument zeigt.
  • Die Spezifikation darf keine Flags, Feldbreiten oder Genauigkeiten 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 darstellt.

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

Die Gleitkommakonversionsfunktionen konvertieren Unendlichkeit in inf oder infinity. Welche Variante verwendet wird, ist implementierungsabhängig.

Nicht-Zahlen werden in nan oder nan(char_sequence) konvertiert. Welche Variante verwendet wird, ist implementierungsabhängig.

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

Der Konvertierungsspezifizierer, der für die Ausgabe von char, unsigned char, signed char, short und unsigned short verwendet wird, erwartet die erhöhten Typen der Standard-Argumentenpromotion, aber vor der Ausgabe seines Wertes wird er in char, unsigned char, signed char, short und unsigned short konvertiert. Es ist sicher, Werte dieser Typen zu übergeben, da die Promotion stattfindet, wenn eine variablen Funktion aufgerufen wird.

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

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

Nach der Ausführung jedes Konvertierungsspezifizierers gibt es einen Sequenzpunkt; dies ermöglicht es, mehrere %n-Ergebnisse in derselben Variablen zu speichern oder, als Grenzfall, einen durch ein früheres %n modifizierten String innerhalb desselben Aufrufs auszugeben.

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

[edit] Rückgabewert

1,4) Die Anzahl der erfolgreich geschriebenen Wide-Zeichen oder ein negativer Wert, wenn ein Fehler aufgetreten ist.
3) Die Anzahl der erfolgreich geschriebenen Wide-Zeichen oder ein negativer Wert, wenn ein Fehler aufgetreten ist. Wenn der resultierende String aufgrund des bufsz-Limits gekürzt wird, gibt die Funktion die Gesamtzahl der Zeichen (ohne das abschließende Null-Wide-Zeichen) zurück, die geschrieben worden wären, wenn das Limit nicht auferlegt worden wäre.
2,5) Anzahl der in den Ausgabestrom übertragenen Wide-Zeichen oder ein negativer Wert bei einem Ausgabefehler, einem Laufzeitfehler aufgrund von Einschränkungsverletzungen oder einem Kodierungsfehler.
6) Anzahl der in den buffer geschriebenen Wide-Zeichen, ohne das Null-Wide-Zeichen (das immer geschrieben wird, solange buffer kein Nullzeiger ist und bufsz nicht Null ist und nicht größer als RSIZE_MAX/sizeof(wchar_t)), oder Null bei Verletzungen von Laufzeiteinschränkungen und ein negativer Wert bei Kodierungsfehlern.
7) Anzahl der Wide-Zeichen, ohne das abschließende Nullzeichen (das immer geschrieben wird, solange buffer kein Nullzeiger ist und bufsz nicht Null ist und nicht größer als RSIZE_MAX/sizeof(wchar_t)), die in buffer geschrieben worden wären, wenn bufsz ignoriert worden wäre, oder ein negativer Wert, wenn eine Verletzung einer Laufzeiteinschränkung oder ein Kodierungsfehler aufgetreten ist.

[edit] Hinweise

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

Während schmale Strings vsnprintf bereitstellen, was die Ermittlung der benötigten Puffergröße ermöglicht, gibt es kein Äquivalent für Wide-Strings (bis C11's vsnwprintf_s). Um die Puffergröße zu ermitteln, muss das Programm möglicherweise vswprintf aufrufen, den Rückgabewert prüfen und einen größeren Puffer neu zuordnen, um es erneut zu versuchen, bis es erfolgreich ist.

vsnwprintf_s kürzt im Gegensatz zu vswprintf_s das Ergebnis, damit es in das von buffer zeigende Array passt, obwohl eine Kürzung bei den meisten grenzgeprüften Funktionen als Fehler behandelt wird.

[edit] 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

[edit] 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)

[edit] Siehe auch

gibt formatierte Ausgaben nach stdout, an einen Dateistream oder in einen Puffer aus
mit variabler Argumentenliste
(Funktion) [bearbeiten]
gibt formatierte Weitzeichenausgaben nach stdout, an einen Dateistream oder in einen Puffer aus
(Funktion) [bearbeiten]
C++ Dokumentation für vwprintf, vfwprintf, vswprintf