| printf(3) | Library Functions Manual | printf(3) |
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf - formatierte Ausgabe
Standard-C-Bibliothek (libc, -lc)
#include <stdio.h>
int printf(const char *restrict format, …);
int fprintf(FILE *restrict datenstrom,
const char *restrict format, …);
int dprintf(int dd,
const char *restrict format, …);
int sprintf(char *restrict zk,
const char *restrict format, …);
int snprintf(char zk[restrict .größe], size_t größe,
const char *restrict format, …);
int vprintf(const char *restrict format, va_list ap);
int vfprintf(FILE *restrict datenstrom,
const char *restrict format, va_list ap);
int vdprintf(int dd,
const char *restrict format, va_list ap);
int vsprintf(char *restrict zk,
const char *restrict format, va_list ap);
int vsnprintf(char zk[restrict .größe], size_t größe,
const char *restrict format, va_list ap);
snprintf(), vsnprintf():
_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
|| /* Glibc <= 2.19: */ _BSD_SOURCE
dprintf(), vdprintf():
Seit Glibc 2.10:
_POSIX_C_SOURCE >= 200809L
Vor Glibc 2.10:
_GNU_SOURCE
Die Funktionenfamilie printf() erzeugt Ausgaben in einem im Folgenden beschriebenen format. Die Funktionen printf() und vprintf() schreiben ihre Ausgabe in den Standardausgabedatenstrom stdout; fprintf() und vfprintf() schreiben in den angegebenen Ausgabedatenstrom datenstrom; sprintf(), snprintf(), vsprintf() und vsnprintf() schreiben in die Zeichenkette zk.
Die Funktion dprintf() ist zu der Funktion fprintf() identisch, außer dass sie in einen Dateideskriptor dd statt in einen stdio(3)-Datenstrom ausgibt.
Die Funktionen snprintf() und vsnprintf() schreiben höchstens größe Bytes (einschließlich des abschließenden Nullbytes (»\0«)) nach zk.
Die Funktionen vprintf(), vfprintf(), vdprintf(), vsprintf(), vsnprintf() sind äquivalent zu den Funktionen printf(), fprintf(),dprintf(), sprintf() bzw. snprintf(), nur dass sie mit einer va_list statt einer variablen Zahl von Argumenten aufgerufen werden. Diese Funktionen rufen das Makro va_end nicht auf. Daher ist der Wert von ap nach dem Aufruf nicht definiert. Siehe stdarg(3).
Alle diese Funktionen schreiben die Ausgabe unter Kontrolle einer format-Zeichenkette, die angibt, wie die folgenden Argumente (oder Argumente, auf die mittels der Möglichkeit der variablen Zahl von Argumenten von stdarg(3) zugegriffen wird) für die Ausgabe konvertiert werden.
C99 und POSIX.1-2001 legen fest, dass die Ergebnisse nicht definiert sind, wenn ein Aufruf von sprintf(), snprintf(), vsprintf() oder vsnprintf() zu einem Kopieren zwischen überlappenden Objekten führen würde (z.B. wenn der Ausgabepuffer und eines der übergebenen Eingabe-Argumente sich auf den gleichen Puffer beziehen). Siehe ANMERKUNGEN.
Die Formatzeichenkette ist eine Zeichenkette, die, so vorhanden, in ihrem initialen Shift-Zustand beginnt und endet. Die Formatzeichenkette setzt sich zusammen aus Null oder mehr Anweisungen: normale Zeichen (nicht %) werden unverändert in den Ausgabedatenstrom kopiert; Umwandlungsanweisungen fordern jeweils null oder mehr Argumente. Jede Umwandlungsanweisung wird durch das Zeichen % eingeleitet und endet mit einem Umwandlungskennzeichner. Dazwischen können (in dieser Reihenfolge) null oder mehr Flags (Schalter), eine optionale minimale Feldbreite, eine optionale Genauigkeit und ein optionaler Längenmodifikator vorkommen.
Pauschal ist die Konvertierungssyntax wie folgt:
%[$][Schalter][Breite][.Genauigkeit][Längenmodifikator]Konvertierung
Die Argumente müssen (nach Typumwandlung) genau zu den Umwandlungskennzeichner passen. Standardmäßig werden die Argumente in der angegebenen Reihenfolge benutzt, wobei jeder »*« (siehe Feldbreite und Genauigkeit weiter unten) und jedes Umwandlungsbezeichner das nächste Argument abfragt (und es ist ein Fehler, wenn nicht ausreichend Argumente angegeben sind). Es kann auch an jeder Stelle, die ein Argument erfordert, explizit angeben werden, welches Argument verwendet wird, indem »%m$« anstelle von »%« und »*m$« anstelle von »*« geschrieben wird, wobei die Dezimalzahl m die Position des gewünschten Arguments in der Argumentliste angibt, beginnend mit 1. Damit sind
printf("%*d", width, num);
und
printf("%2$*1$d", width, num);
gleichwertig. Die zweite Form ermöglicht wiederholte Referenzen auf das gleiche Argument. Der C99-Standard schließt die aus der Single Unix Specification stammende Form mit »$« nicht mit ein. Wenn die »$« verwendende Form eingesetzt wird, muss sie durchgehend für alle Umwandlungen, die ein Argument erfordern, und alle Breiten- und Genauigkeitsargumente verwendet werden, darf aber mit »%%«-Formaten (die kein Argument erfordern) vermischt werden. Es darf keine Lücken in der Zahl der mittels »$« spezifizierten Argumente geben; beispielsweise muss, wenn die Argumente 1 und 3 angegeben werden, auch Argument 2 irgendwo in der Formatzeichenkette erwähnt werden.
Für einige numerische Umwandlungen wird ein Radixzeichen (»Dezimalpunkt«) oder ein Tausender-Gruppierungszeichen verwendet. Das tatsächlich benutzte Zeichen hängt von der LC_NUMERIC-Komponente der Locale ab (siehe setlocale(3)). Die POSIX-Locale benutzt ».« als Radixzeichen und hat kein Gruppierungszeichen. Damit resultiert
printf("%'.2f", 1234567.89);
in »1234567.89« in der POSIX-Locale, in »1234567,89« in der Locale nl_NL und in »1.234.567,89« in der Locale da_DK.
Dem Zeichen % folgen null oder mehr der folgenden Schalter:
Die obigen fünf Schalter werden vom C99-Standard definiert. Die Single UNIX Specification spezifiziert einen weiteren Schalter.
Glibc 2.2 fügt ein weiteres Schalterzeichen hinzu.
Diese optionale Dezimalzahl gibt die minimale Feldbreite an; die erste Ziffer ist von Null verschieden. Wenn der umgewandelte Wert weniger Zeichen als die Feldbreite hat, wird er links mit Leerzeichen aufgefüllt (oder rechts, wenn der Schalter für Linksbündigkeit gesetzt ist). Statt einer Dezimalzahl kann auch »*« oder »*m$« (für irgendeine Ganzzahl m) angegeben werden, um zu spezifizieren, dass die Feldbreite im nächsten (oder m-ten) Argument gegeben ist, welches vom Type int sein muss. Eine negative Feldbreite wird als Schalter »-« gefolgt von einer positiven Breite interpretiert. In keinem Fall bewirkt eine fehlende oder kleine Feldbreite das Abschneiden eines Feldes; ist das Ergebnis einer Umwandlung breiter als die Feldbreite, so wird das Feld erweitert, um das Ergebnis aufzunehmen.
Eine optionale Genauigkeit in der Form eines Punkts (».«) gefolgt von einer optionalen Dezimalzahl. Statt einer Dezimalzahl kann auch mittels »*« oder »*m$« (für irgendeine Dezimalzahl m) angegeben werden, dass die Genauigkeit im nächsten (oder m-ten) Argument gegeben ist, welches den Typ int haben muss. Falls die Genauigkeit einfach als ».« angegeben ist, wird eine dafür der Wert Null angenommen. Eine negative Genauigkeit wird angenommen, falls die Genauigkeitsangabe weggelassen wird. Dies gibt die minimale Anzahl der Ziffern an, die bei den Umwandlungen d, i, o, u, x und X erscheinen, bzw. die Anzahl der Ziffern nach dem Dezimaltrennzeichen bei a, A, e, E, f und F, die maximale Anzahl von signifikanten Ziffern bei g und G oder die maximale Anzahl von auszugebenden Zeichen einer Zeichenkette bei s und S.
Im Folgenden steht »Ganzzahlumwandlung« für d, i, o, u, x oder X.
SUSv3 spezifiziert alle oben genannten, außer den Modifikatoren, die explizit als nicht standardisierte Erweiterungen vermerkt sind. SUSv2 kennt nur die Längenmodifikatoren h (in hd, hi, ho, hx, hX, hn) und l (in ld, li, lo, lx, lX, ln, lc, ls) und L (in Le, LE, Lf, Lg, LG).
Als eine nicht standardisierte Erweiterung behandelt die GNU-Implementierung ll und L als Synonyme, so dass Sie llg (als Synonym für das standardmäßige Lg) und Ld (als Synonym für das standardmäßige lld) schreiben können. Dies ist nicht portabel.
Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt. Die Umwandlungskennzeichner und ihre Bedeutung sind:
Nach erfolgreicher Ausführung geben diese Funktionen die Anzahl der ausgegebenen Zeichen zurück (ohne das für den Abschluß der Zeichenkettenausgabe verwendete Nullbyte).
Die Funktionen snprintf() und vsnprintf() schreiben nicht mehr als größe Byte (einschließlich des abschließenden Nullbytes »\0«)). Falls die Ausgabe wegen dieser Begrenzung gekürzt wurde, ist der Rückgabewert die Anzahl der Zeichen (ohne abschließendes Nullbyte), die bei ausreichendem Speicherplatz in die Ausgabe geschrieben worden wären. Damit bedeutet ein Rückgabewert von größe oder mehr, dass die Ausgabe gekürzt wurde. (Siehe auch im Folgenden unter ANMERKUNGEN.)
Wenn bei der Ausgabe ein Fehler auftritt, wird ein negativer Wert zurückgegeben.
Glibc 2.1 fügt die Längenmodifikatoren hh, j, t und z sowie die Umwandlungszeichen a und A hinzu.
Glibc 2.2 fügt das Umwandlungszeichen F mit C99-Semantik sowie den Schalter l hinzu.
Glibc 2.35 gibt der alternativen Form (#) des Umwandlungskennzeichners m eine Bedeutung, nämlich %#m.
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
| Schnittstelle | Attribut | Wert |
| printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf() | Multithread-Fähigkeit | MT-Safe locale |
fprintf(), printf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99.
Die Funktionen dprintf() und vdprintf() waren ursprünglich GNU-Erweiterungen, die später in POSIX.1-2008 standardisiert wurden.
Hinsichtlich des Rückgabewerts von snprintf() widersprechen sich SUSv2 und der C99-Standard: wird snprintf() mit größe=0 aufgerufen, dann fordert SUSv2 einen nicht spezifizierten Rückgabewert kleiner als 1, während C99 es zulässt, dass zk in diesem Fall NULL ist, und (wie immer) den Rückgabewert als die Anzahl der Zeichen angibt, die bei ausreichend großer Ausgabe-Zeichenkette geschrieben worden wären. POSIX.1-2001 und neuer richten ihre Spezifikation von snprintf() an C99 aus.
Einige Programme verlassen sich leichtsinnig auf Code wie den folgenden
sprintf(buf, "%s etwas mehr Text", buf);
um Text an buf anzuhängen. Jedoch weisen die Standards explizit darauf hin, dass die Ergebnisse undefiniert sind, wenn Quell- und Ziel-Puffer beim Aufruf von sprintf(), snprintf(), vsprintf() und vsnprintf() überlappen. Abhängig von der verwendeten gcc(1)-Version und den gewählten Compiler-Optionen erzeugen Aufrufe wie das obige Beispiel nicht die erwarteten Ergebnisse.
Seit der Glibc-Version 2.1 ist die Implementierung der Funktionen snprintf() und vsnprintf() konform zu C99, verhält sich also wie oben beschrieben. Bis Glibc 2.0.6 gaben sie im Fall gekürzter Ausgaben -1 zurück.
Da sprintf() und vsprintf() eine beliebig lange Zeichenkette annehmen, müssen Aufrufende darauf achten, nicht den tatsächlich verfügbaren Platz zu überschreiten; dies ist oft unmöglich sicherzustellen. Beachten Sie, dass die Länge der Zeichenketten oft abhängig von der Locale und schwierig vorherzusagen sind. Benutzen Sie stattdessen snprintf() und vsnprintf() (oder asprintf(3) und vasprintf(3)).
Code wie beispielsweise printf(foo); weist häufig auf einen Fehler hin, da foo das Zeichen »%« enthalten kann. Stammt foo von ungeprüfter Nutzereingabe, kann es »%n« enthalten und veranlasst printf(), in den Speicher zu schreiben und erzeugt damit ein Sicherheitsloch.
Um Pi mit fünf Dezimalstellen auszugeben:
#include <math.h> #include <stdio.h> fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
Um Datum und Zeit in der Form »Sunday, July 3, 10:02« auszugeben, wobei weekday und month Zeiger auf Zeichenketten sind:
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
Die meisten Länder verwenden die Reihenfolge Tag-Monat-Jahr. Deshalb muss eine internationalisierte Version in der Lage sein, die Argumente in der durch das Format angegebenen Reihenfolge zu drucken:
#include <stdio.h>
fprintf(stdout, format,
weekday, month, day, hour, min);
wobei format von der Locale abhängt und möglicherweise die Argumente vertauscht. Mit dem Wert
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
könnte dann »Sonntag, 3. Juli, 10:02« dabei herauskommen.
Um eine genügend große Zeichenkette bereitzustellen und in sie zu schreiben (der Code ist korrekt sowohl für Glibc 2.0 als auch Glibc 2.1):
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *
make_message(const char *fmt, …)
{
int n = 0;
size_t size = 0;
char *p = NULL;
va_list ap;
/* Benötigte Größe ermitteln. */
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0)
return NULL;
size = (size_t) n + 1; /* Ein zusätzliches Byte für »\0« */
p = malloc(size);
if (p == NULL)
return NULL;
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0) {
free(p);
return NULL;
}
return p;
}
Bei Kürzungen in Glibc-Versionen vor 2.0.6 wird dies als ein Fehler aufgefasst und nicht wohlwollend behandelt.
printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)
Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer <Martin.E.Schauer@gmx.de>, Mario Blättermann <mario.blaettermann@gmail.com> und Helge Kreutzmann <debian@helgefjell.de> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Übersetzer.
| 5. Februar 2023 | Linux man-pages 6.03 |