Namespaces
Variants

    wprintf, fwprintf, swprintf, wprintf_s, fwprintf_s, swprintf_s, snwprintf_s

    Von de.cppreference.net
    < c | io
     
    C
     
    Datei-Eingabe/-Ausgabe
    Typen und Objekte
            
    Funktionen
    Dateizugriff
    (C11)
    (C11)  
    (C95)
    Unformatierte Eingabe/Ausgabe
    (C95)(C95)
    (C95)
    (C95)(C95)
    (C95)
    (C95)
    (C95)
    (C95)

    Formatierte Eingabe
    (C99)(C99)(C99)(C11)(C11)(C11)
    (C99)(C99)(C99)(C11)(C11)(C11)  
    Direkte Eingabe/Ausgabe
    Formatierte Ausgabe
    Dateipositionierung
    Fehlerbehandlung
    Operationen auf Dateien
     
    Definiert in Header <wchar.h> 
    int wprintf( const wchar_t* format, ... );
    		(1) (seit C95)
    (bis C99)    		 
    int wprintf( const wchar_t* restrict format, ... );
    		(seit C99) 
    int fwprintf( FILE* stream, const wchar_t* format, ... );
    		(2) (seit C95)
    (bis C99)    		 
    int fwprintf( FILE* restrict stream,
              const wchar_t* restrict format, ... );
    		(seit C99) 
    int swprintf( wchar_t* buffer, size_t bufsz,
              const wchar_t* format, ... );
    		(3) (seit C95)
    (bis C99)    		 
    int swprintf( wchar_t* restrict buffer, size_t bufsz,
              const wchar_t* restrict format, ... );
    		(seit C99) 
    int wprintf_s( const wchar_t* restrict format, ... );
    		(4) (seit C11) 
    int fwprintf_s( FILE* restrict stream,
                const wchar_t* restrict format, ... );
    		(5) (seit C11) 
    int swprintf_s( wchar_t* restrict buffer, rsize_t bufsz,
                const wchar_t* restrict format, ... );
    		(6) (seit C11) 
    int snwprintf_s( wchar_t* restrict s, rsize_t n,
                 const wchar_t* restrict format, ... );
    		(7) (seit C11)

    Lädt die Daten von den angegebenen Orten, konvertiert sie in breite Zeichenkettenäquivalente und schreibt die Ergebnisse in verschiedene Ziele.

    1) Schreibt die Ergebnisse in stdout.
    2) Schreibt die Ergebnisse in einen Dateistrom stream.
    3) Wenn bufsz größer als Null ist, schreibt die Ergebnisse in eine breite Zeichenkette buffer. Es werden höchstens bufsz - 1 breite Zeichen gefolgt von einem Null-Breitzeichen geschrieben. Wenn bufsz Null ist, wird nichts geschrieben (und buffer kann ein Nullzeiger sein).
    4-6) Gleich wie (1-3), mit der Ausnahme, dass die folgenden Fehler zur Laufzeit erkannt werden und die derzeit installierte Einschränkungshandler-Funktion aufrufen:
    • Das Konvertierungsspezifikationszeichen %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)
    • Bei Zeichenketten- und Zeichen-Konvertierungsspezifikationen treten Kodierungsfehler auf.
    • (nur für swprintf_s) Die Anzahl der zu schreibenden Breitzeichen, einschließlich der Null, würde bufsz überschreiten.
    7) Gleich wie (6), mit der Ausnahme, dass das Ergebnis abgeschnitten wird, um in das durch s gegebene Array zu passen.
    Wie bei allen grenzgeprüften Funktionen sind wprintf_s, fwprintf_s, swprintf_s und snwprintf_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ auf die ganzzahlige Konstante 1 setzt, bevor er <stdio.h> einbindet.

    Parameter

    stream - Ausgabe-Dateistrom zum Schreiben
    buffer - Zeiger auf eine breite Zeichenkette zum Schreiben
    bufsz - bis zu bufsz - 1 breite Zeichen können geschrieben werden, plus der Null-Terminator
    format - Zeiger auf eine nullterminierte breite Zeichenkette, die angibt, wie die Daten zu interpretieren sind
    ... - Argumente, die die zu druckenden Daten angeben. Wenn irgendein Argument nach den Standard-Argumentpromotionen nicht dem Typ entspricht, der vom entsprechenden Konvertierungsspezifikator erwartet wird, oder wenn weniger Argumente als von format benötigt vorhanden sind, ist das Verhalten undefiniert. Wenn mehr Argumente als von format benötigt vorhanden sind, werden die überzähligen Argumente ausgewertet und ignoriert.


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

    • Einführendes % 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 signed-Konvertierungen wird immer dem Ergebnis der Konvertierung vorangestellt (standardmäßig wird dem Ergebnis nur dann ein Minus vorangestellt, wenn es negativ ist).
    • Leerzeichen: Wenn das Ergebnis einer signed-Konvertierung nicht mit einem Vorzeichen beginnt oder leer ist, wird ein Leerzeichen vorangestellt. Es wird ignoriert, wenn das +-Flag vorhanden ist.
    • #: Es wird die alternative Form der Konvertierung durchgeführt. Siehe untenstehende Tabelle für genaue Auswirkungen, andernfalls ist das Verhalten undefiniert.
    • 0: Bei Ganzzahl- und Gleitkommazahlen-Konvertierungen werden führende Nullen anstelle von Leerzeichen 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 Leerzeichen aufgefüllt, links, wenn rechtsbündig, oder rechts, wenn linksbündig. Wenn * verwendet wird, wird die Breite durch ein zusätzliches Argument vom Typ int angegeben, das vor dem zu konvertierenden Argument und gegebenenfalls dem Argument, das die Genauigkeit liefert, erscheint. Wenn der Wert des Arguments negativ ist, führt dies zum angegebenen --Flag und positiver Feldbreite (Hinweis: Dies ist die Mindestbreite: Der Wert wird niemals abgeschnitten).
    • (optional) . gefolgt von einer ganzen Zahl oder *, oder keins von beiden, 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, das die minimale Feldbreite liefert, falls vorhanden, erscheint. Ist der Wert dieses Arguments negativ, wird es ignoriert. Wenn weder eine Zahl noch * verwendet wird, wird die Genauigkeit als Null angenommen. Siehe untenstehende Tabelle für die genauen Auswirkungen der Genauigkeit.
    • (optional) Längenmodifikator, der die Größe des Arguments angibt (in Kombination mit dem Konvertierungsformatspezifikator gibt er den Typ des entsprechenden Arguments an).
    • Konvertierungsformatspezifikator.

    Die folgenden Formatspezifikatoren sind verfügbar:

    Konvertierungs-
    Spezifikator     		Erklärung Erwarteter
    Argumenttyp
    Längenmodifikator→ hh h kein l ll j z t L
    Nur verfügbar seit C99→ Ja Ja Ja Ja Ja
    % Schreibt Literal %. 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 eine Zeichenkette.

    • Das Argument muss ein Zeiger auf das erste Element eines Zeichen-Arrays sein, das eine Multibyte-Zeichensequenz enthält, die im anfänglichen Umschaltzustand beginnt, und die wie durch einen Aufruf von mbrtowc mit nullinitialisiertem Konvertierungszustand in ein Breitzeichen-Array konvertiert wird.
    • Genauigkeit gibt die maximale Anzahl von Breitzeichen an, die geschrieben werden sollen. Wenn Genauigkeit nicht angegeben ist, werden alle Breitzeichen bis einschließlich des ersten Nullterminators geschrieben.
    • Wenn der l-Spezifikator 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 signed Ganzzahl in dezimale Darstellung [-]dddd.

    • Genauigkeit gibt die Mindestanzahl 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 signed-Version von size_t.
    signed char
    short
    int
    long
    long long
    intmax_t
    ※
    ptrdiff_t
    		 N/A
    b
    B (optional)

    (C23)

    Konvertiert eine unsigned Ganzzahl in binäre Darstellung bbbb.

    • Genauigkeit gibt die Mindestanzahl 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 0b oder 0B wird dem Ergebnis ein Präfix vorangestellt, wenn der konvertierte Wert ungleich Null ist.
    unsigned char
    unsigned short
    unsigned int
    unsigned long
    unsigned long long
    uintmax_t
    size_t
    unsigned Version von ptrdiff_t
    		 N/A
    o

    Konvertiert eine unsigned Ganzzahl in oktale Darstellung oooo.

    • Genauigkeit gibt die Mindestanzahl 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 wird, wenn sowohl der konvertierte Wert als auch die Genauigkeit 0 sind, ein einzelnes 0 geschrieben.
    		 N/A
    x
    X

    Konvertiert eine unsigned Ganzzahl in 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 Mindestanzahl 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 0x oder 0X wird dem Ergebnis ein Präfix vorangestellt, wenn der konvertierte Wert ungleich Null ist.
    		 N/A
    u

    Konvertiert eine unsigned Ganzzahl in dezimale Darstellung dddd.

    • Genauigkeit gibt die Mindestanzahl 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 Gleitkommazahl in die Dezimalnotation im Stil [-]ddd.ddd.

    • Genauigkeit gibt die genaue Anzahl der nach dem Dezimaltrennzeichen anzuzeigenden Ziffern an.
    • Die Standardgenauigkeit ist 6.
    • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern folgen.
    • Für Unendlich- und NaN-Konvertierungsstile siehe Anmerkungen.
    		 N/A N/A
    double
    double (C99)
    		 N/A N/A N/A N/A
    long double
    e
    E

    Konvertiert Gleitkommazahl in die dezimale Exponentennotation.

    • 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, mehr Ziffern werden nur bei Bedarf verwendet.
    • Wenn der Wert 0 ist, ist der Exponent auch 0.
    • Genauigkeit gibt die genaue Anzahl der nach dem Dezimaltrennzeichen anzuzeigenden Ziffern an.
    • Die Standardgenauigkeit ist 6.
    • In der alternativen Implementierung wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern folgen.
    • Für Unendlich- und NaN-Konvertierungsstile siehe Anmerkungen.
    		 N/A N/A N/A N/A N/A N/A
    a
    A

    (C99)

    Konvertiert Gleitkommazahl in die hexadezimale Exponentennotation.

    • 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 auch 0.
    • Genauigkeit gibt die genaue Anzahl der nach dem Hexadezimaltrennzeichen anzuzeigenden 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 folgen.
    • Für Unendlich- und NaN-Konvertierungsstile siehe Anmerkungen.
    		 N/A N/A N/A N/A N/A N/A
    g
    G

    Konvertiert Gleitkommazahl in dezimale oder dezimale Exponentennotation, 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, wird die Konvertierung mit Stil f oder F(seit C99) und Genauigkeit P − 1 − X durchgeführt.
      • Andernfalls wird die Konvertierung mit Stil e oder E und Genauigkeit P − 1 durchgeführt.
    • Sofern keine alternative Darstellung angefordert wird, werden die nachgestellten Nullen entfernt, ebenso wird das Dezimaltrennzeichen entfernt, wenn kein Bruchteil übrig bleibt.
    • Für Unendlich- und NaN-Konvertierungsstile siehe Anmerkungen.
    		 N/A N/A N/A N/A N/A N/A
    n

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

    • Das Ergebnis wird geschrieben in den Wert, auf den das Argument zeigt.
    • Die Spezifikation darf keine Flag, Feldbreite oder Genauigkeit enthalten.
    • Für den z-Modifikator ist der erwartete Argumenttyp S*, wobei S die signed-Version von size_t ist.
    signed char*
    short*
    int*
    long*
    long long*
    intmax_t*
    ※
     ptrdiff_t* 
    		 N/A
    p

    Schreibt eine implementationsdefinierte 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. Welche verwendet wird, ist implementationsdefiniert.

    NaN wird in nan oder nan(char_sequence) konvertiert. Welche verwendet wird, ist implementationsdefiniert.

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

    Der Konvertierungsspezifikator, der zum Drucken von char, unsigned char, signed char, short und unsigned short verwendet wird, erwartet promotete Typen der Standard-Argumentpromotionen, 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, aufgrund der Promotion, die beim Aufruf einer variadischen Funktion stattfindet.

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

    Der speicher-schreibende Konvertierungsspezifikator %n ist ein häufiges Ziel von Sicherheitsausnutzungen, bei denen Formatzeichenketten 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 Konvertierungsspezifikators; 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,2) Anzahl der geschriebenen Breitzeichen bei Erfolg oder negativer Wert bei Fehler.
    3) Anzahl der geschriebenen Breitzeichen (ohne das abschließende Null-Breitzeichen) bei Erfolg oder negativer Wert, wenn ein Kodierungsfehler aufgetreten ist oder die Anzahl der zu erzeugenden Zeichen gleich oder größer als bufsz war (auch wenn bufsz Null ist).
    4,5) Anzahl der geschriebenen Breitzeichen bei Erfolg oder negativer Wert bei Fehler.
    6) Anzahl der Breitzeichen (ohne die abschließende Null), die in buffer geschrieben wurden. Gibt einen negativen Wert bei Kodierungsfehlern und Überlauf zurück. Gibt Null bei allen anderen Fehlern zurück.
    7) Anzahl der Breitzeichen (ohne die abschließende Null), die in buffer geschrieben worden wären, wenn bufsz ausreichend groß gewesen wäre, oder ein negativer Wert, wenn ein Fehler auftritt. (d.h., der Schreibvorgang war erfolgreich und vollständig nur, wenn der Rückgabewert nicht negativ und kleiner als bufsz ist)

    Anmerkungen

    Während schmale Zeichenketten snprintf bereitstellen, was es ermöglicht, die erforderliche Ausgabepuffergröße zu bestimmen, gibt es kein Äquivalent für breite Zeichenketten (bis snwprintf_s)(seit C11), und um die Puffergröße zu bestimmen, muss das Programm möglicherweise swprintf aufrufen, den Rückgabewert überprüfen, einen größeren Puffer neu zuweisen und es erneut versuchen, bis es erfolgreich ist.

    snwprintf_s, anders als swprintf_s, wird das Ergebnis abschneiden, um in das durch buffer gegebene Array zu passen, obwohl das Abschneiden von den meisten grenzgeprüften Funktionen als Fehler behandelt wird.

    Beispiel

    Diesen Code ausführen
    #include <locale.h>
#include <wchar.h>

int main(void)
{
    char narrow_str[] = "z\u00df\u6c34\U0001f34c";
                  // or "zß水🍌"
                  // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c";
    wchar_t warr[29]; // the expected string is 28 characters plus 1 null terminator
    setlocale(LC_ALL, "en_US.utf8");
    swprintf(warr, sizeof warr / sizeof* warr,
             L"Converted from UTF-8: '%s'", narrow_str);
    wprintf(L"%ls\n", warr);
}

    Ausgabe: 

    Converted from UTF-8: 'zß水🍌'

    Referenzen

    • C23-Standard (ISO/IEC 9899:2024):
    • 7.29.2.1 Die fwprintf-Funktion (S. TBD)
    • 7.29.2.3 Die swprintf-Funktion (S. TBD)
    • 7.29.2.11 Die wprintf-Funktion (S. TBD)
    • K.3.9.1.1 Die fwprintf_s-Funktion (S. TBD)
    • K.3.9.1.4 Die swprintf_s-Funktion (S. TBD)
    • K.3.9.1.13 Die wprintf_s-Funktion (S. TBD)
    • C17-Standard (ISO/IEC 9899:2018):
    • 7.29.2.1 Die fwprintf-Funktion (S. TBD)
    • 7.29.2.3 Die swprintf-Funktion (S. TBD)
    • 7.29.2.11 Die wprintf-Funktion (S. TBD)
    • K.3.9.1.1 Die fwprintf_s-Funktion (S. TBD)
    • K.3.9.1.4 Die swprintf_s-Funktion (S. TBD)
    • K.3.9.1.13 Die wprintf_s-Funktion (S. TBD)
    • C11-Standard (ISO/IEC 9899:2011):
    • 7.29.2.1 Die fwprintf-Funktion (S. 403-410)
    • 7.29.2.3 Die swprintf-Funktion (S. 416)
    • 7.29.2.11 Die wprintf-Funktion (S. 421)
    • K.3.9.1.1 Die fwprintf_s-Funktion (S. 628)
    • K.3.9.1.4 Die swprintf_s-Funktion (S. 630-631)
    • K.3.9.1.13 Die wprintf_s-Funktion (S. 637-638)
    • C99-Standard (ISO/IEC 9899:1999):
    • 7.24.2.1 Die fwprintf-Funktion (S. 349-356)
    • 7.24.2.3 Die swprintf-Funktion (S. 362)
    • 7.24.2.11 Die wprintf-Funktion (S. 366)

    Siehe auch

    (C99)(C11)(C11)(C11)(C11)
    		 gibt formatierte Ausgabe in stdout, einen Dateistrom oder einen Puffer aus
    (Funktion)
    (C95)(C95)(C95)(C11)(C11)(C11)(C11)
    		 gibt formatierte Breitzeichen-Ausgabe in stdout, einen Dateistrom
    oder einen Puffer unter Verwendung einer variablen Argumentliste aus
    (Funktion)
    (C95)
    		 schreibt eine breite Zeichenkette in einen Dateistrom
    (Funktion)
    C++-Dokumentation für wprintf, fwprintf, swprintf