vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s
| 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.
- der Konvertierungsspezifizierer
%nim format vorhanden ist - eines der Argumente, die
%sentsprechen, 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.
- der Konvertierungsspezifizierer
- Wie bei allen grenzgeprüften Funktionen sind
vwprintf_s,vfwprintf_s,vswprintf_sundvsnwprintf_snur 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.
- ein einführendes
- (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) Ganzzahlwert oder
- (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)
- (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.
|
N/A | N/A | int |
wint_t |
N/A | N/A | N/A | N/A | N/A |
s
|
Schreibt eine Zeichenkette.
|
N/A | N/A | char* |
wchar_t* |
N/A | N/A | N/A | N/A | N/A |
di
|
Konvertiert eine vorzeichenbehaftete Ganzzahl in die Dezimaldarstellung [-]dddd.
|
signed char |
short |
int |
long |
long long |
※ |
N/A | ||
o
|
Konvertiert eine vorzeichenlose Ganzzahl in die Oktaldarstellung oooo.
|
unsigned char |
unsigned short |
unsigned int |
unsigned long |
unsigned long long |
vorzeichenbehaftete Version von ptrdiff_t |
N/A | ||
xX
|
Konvertiert eine vorzeichenlose Ganzzahl in die Hexadezimaldarstellung hhhh.
|
N/A | ||||||||
u
|
Konvertiert eine vorzeichenlose Ganzzahl in die Dezimaldarstellung dddd.
|
N/A | ||||||||
fF (C99)
|
Konvertiert eine Gleitkommazahl in die Dezimalnotation im Stil [-]ddd.ddd.
|
N/A | N/A | double |
double (C99) |
N/A | N/A | N/A | N/A | long double |
eE
|
Konvertiert eine Gleitkommazahl in die Dezimal-Exponent-Notation.
|
N/A | N/A | N/A | N/A | N/A | N/A | |||
aA
(C99) |
Konvertiert eine Gleitkommazahl in die Hexadezimal-Exponent-Notation.
|
N/A | N/A | N/A | N/A | N/A | N/A | |||
gG
|
Konvertiert eine Gleitkommazahl je nach Wert und Genauigkeit in die Dezimal- oder Dezimal-Exponent-Notation.
|
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.
|
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 Nicht-Zahlen werden in Die Konversionen 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 Der Speicher schreibende Konvertierungsspezifizierer Nach der Ausführung jedes Konvertierungsspezifizierers gibt es einen Sequenzpunkt; dies ermöglicht es, mehrere Wenn eine Konversionsspezifikation ungültig ist, ist das Verhalten undefiniert. | ||||||||||
[edit] Rückgabewert
RSIZE_MAX/sizeof(wchar_t)), oder Null bei Verletzungen von Laufzeiteinschränkungen und ein negativer Wert bei Kodierungsfehlern.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
| (C99)(C11)(C11)(C11)(C11) |
gibt formatierte Ausgaben nach stdout, an einen Dateistream oder in einen Puffer aus mit variabler Argumentenliste (Funktion) |
| (C95)(C95)(C95)(C11)(C11)(C11)(C11) |
gibt formatierte Weitzeichenausgaben nach stdout, an einen Dateistream oder in einen Puffer aus (Funktion) |
| C++ Dokumentation für vwprintf, vfwprintf, vswprintf
| |