Namespaces
Variants

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

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
(C99) (C11) (C11) (C11) (C11)
vwprintf vfwprintf vswprintf vwprintf_s vfwprintf_s vswprintf_s vsnwprintf_s
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
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 die Daten von Orten, definiert durch vlist , konvertiert sie in Wide-String-Äquivalente 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 Breitzeichen-String buffer . Es werden maximal bufsz - 1 Breitzeichen geschrieben, gefolgt von einem Null-Breitzeichen. Der resultierende Breitzeichen-String wird mit einem Null-Breitzeichen abgeschlossen, es sei denn bufsz ist null.
4-6) Gleich wie (1-3) , außer dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler -Funktion aufrufen:
  • das Konvertierungsspezifizierer %n in 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
  • Kodierungsfehler in einem der String- und Zeichenkonvertierungsspezifizierer auftreten
  • (nur für vswprintf_s ), der in buffer zu speichernde String (einschließlich des abschließenden breiten Nullzeichens) bufsz überschreiten würde.
7) Gleich wie (6) , außer 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__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf den ganzzahligen Konstantenwert 1 setzt, bevor <stdio.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

stream - Ausgabe-Breitzeichenstrom, in den geschrieben wird
buffer - Zeiger auf eine Breitzeichenkette, in die geschrieben wird
bufsz - maximale Anzahl an Breitzeichen, die geschrieben werden
format - Zeiger auf eine nullterminierte Breitzeichenkette, die die Dateninterpretation spezifiziert
vlist - variable Argumentenliste mit den auszugebenden Daten.


Die Format -Zeichenkette besteht aus gewöhnlichen Breitzeichen (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 Minus nur bei negativen Ergebnissen vorangestellt).
  • space : wenn das Ergebnis einer vorzeichenbehafteten Konvertierung nicht mit einem Vorzeichen beginnt oder leer ist, wird ein Leerzeichen dem Ergebnis 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 statt 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 wchar_t konvertiert, wie durch den Aufruf 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. Diese wird in ein Wide-Character-Array konvertiert, als ob durch einen Aufruf von mbrtowc mit einem nullinitialisierten Konvertierungszustand.
  • Präzision spezifiziert die maximale Anzahl an Wide Characters, die geschrieben werden sollen. Wenn Präzision nicht angegeben ist, werden alle Wide Characters 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.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

Wandelt einen vorzeichenbehafteten Integer 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

Konvertiert eine vorzeichenlose Ganzzahl in die Oktaldarstellung oooo .

  • 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 Mindestanzahl 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 beträgt 6 .
  • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern 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

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 einen normalisierten Gleitkommawert darstellt.
  • Wenn der Wert ​ 0 ​ ist, ist der Exponent ebenfalls ​ 0 ​ .
  • Präzision gibt die exakte Anzahl der Ziffern nach dem hexadezimalen Punktzeichen an.
  • 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 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 signierte Version von size_t ist.
signed char *
short *
int *
long *
long long *
※
N/A
p

Schreibt eine implementierungsdefinierte Zeichensequenz, die einen Pointer 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 festbreiten Zeichentypen ( int8_t , etc) sind im Header <inttypes.h> definiert (obwohl PRIdMAX , PRIuMAX , etc synonym mit %jd , %ju , etc ist).

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,4) Die Anzahl der geschriebenen Breitzeichen bei Erfolg oder ein negativer Wert bei einem Fehler.
3) Die Anzahl der geschriebenen Breitzeichen bei Erfolg oder ein negativer Wert bei einem Fehler. Wenn die resultierende Zeichenkette aufgrund des bufsz Limits abgeschnitten wird, gibt die Funktion die Gesamtanzahl der Zeichen (ohne das abschließende Null-Breitzeichen) zurück, die geschrieben worden wären, wenn das Limit nicht auferlegt worden wäre.
2,5) Anzahl der an den Ausgabestream übertragenen Breitzeichen oder ein negativer Wert, falls ein Ausgabefehler, ein Verstoß gegen Laufzeitbeschränkungen oder ein Kodierungsfehler aufgetreten ist.
6) Anzahl der in den buffer geschriebenen Breitzeichen, ohne das Null-Breitzeichen zu zählen (welches 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 Laufzeitbedingungsverletzungen, und negativer Wert bei Kodierungsfehlern.
7) Anzahl der Breitzeichen 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/sizeof(wchar_t) 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 va_end nicht auf, und dies muss vom Aufrufer durchgeführt werden.

Während schmale Zeichenketten vsnprintf bereitstellen, was die Bestimmung der erforderlichen Ausgabepuffergröße ermöglicht, gibt es keine Entsprechung für breite Zeichenketten (bis zu C11s vsnwprintf_s), und um die Puffergröße zu bestimmen, muss das Programm möglicherweise vswprintf aufrufen, den Rückgabewert prüfen und einen größeren Puffer neu zuweisen und erneut versuchen, bis es erfolgreich ist.

vsnwprintf_s , im Gegensatz zu vswprintf_s , wird das Ergebnis kürzen, um in das durch buffer zeigende Array zu passen, obwohl Kürzung von den meisten grenzprüfenden Funktionen als Fehler behandelt wird.

Beispiel

Diesen Code ausführen 
#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 vfwprintf-Funktion (S.: TBD)
  • 7.29.2.7 Die vswprintf-Funktion (S.: TBD)
  • 7.29.2.9 Die vwprintf-Funktion (S.: TBD)
  • K.3.9.1.6 Die vfwprintf_s-Funktion (S.: TBD)
  • K.3.9.1.8 Die vsnwprintf_s-Funktion (S.: TBD)
  • K.3.9.1.9 Die vswprintf_s-Funktion (S.: TBD)
  • K.3.9.1.11 Die vwprintf_s-Funktion (S.: TBD)
  • C17-Standard (ISO/IEC 9899:2018):
  • 7.29.2.5 Die vfwprintf-Funktion (S.: TBD)
  • 7.29.2.7 Die vswprintf-Funktion (S.: TBD)
  • 7.29.2.9 Die vwprintf-Funktion (S.: TBD)
  • K.3.9.1.6 Die vfwprintf_s-Funktion (S.: TBD)
  • K.3.9.1.8 Die vsnwprintf_s-Funktion (S.: TBD)
  • K.3.9.1.9 Die vswprintf_s-Funktion (S.: TBD)
  • K.3.9.1.11 Die vwprintf_s-Funktion (S.: TBD)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.29.2.5 Die vfwprintf-Funktion (S: 417-418)
  • 7.29.2.7 Die vswprintf-Funktion (S: 419)
  • 7.29.2.9 Die vwprintf-Funktion (S: 420)
  • K.3.9.1.6 Die vfwprintf_s-Funktion (S: 632)
  • K.3.9.1.8 Die vsnwprintf_s-Funktion (S: 633-634)
  • K.3.9.1.9 Die vswprintf_s-Funktion (S: 634-635)
  • K.3.9.1.11 Die vwprintf_s-Funktion (S: 636)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.24.2.5 Die vfwprintf-Funktion (S: 363)
  • 7.24.2.7 Die vswprintf-Funktion (S: 364)
  • 7.24.2.9 Die vwprintf-Funktion (S: 365)

Siehe auch

(C99) (C11) (C11) (C11) (C11)
formatiert Ausgabe an stdout , einen Dateistrom oder einen Puffer
unter Verwendung einer variablen Argumentenliste
(Funktion)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
formatiert Breitzeichen-Ausgabe an stdout , einen Dateistrom oder einen Puffer
(Funktion)
C++-Dokumentation für vwprintf , vfwprintf , vswprintf