Manpage  — PRINTF

printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatierte Ausgabe

ÜBERSICHT BESCHREIBUNG Rückgabewert Format des Formatstrings Die Zeichen für die Flags Die Feldbreite Die Genauigkeit Der Längenmodifikator Der Umwandlungsspezifikator BEISPIELE SIEHE AUCH STANDARDS GESCHICHTE BUGS

#include <stdio.h>

int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format, ...);
int asprintf(char **strp, const char *format, ...);
int dprintf(int d, const char *format, ...);

#include <stdarg.h>

int vprintf(const char *format, va_list ap);
int vfprintf(FILE *stream, const char *format, va_list ap);
int vsprintf(char *str, const char *format, va_list ap);
int vsnprintf(char *str, size_t size, const char *format, va_list ap);
int vasprintf(char **strp, const char *format, va_list ap);
int vdprintf(int d, const char *format, va_list ap);

Diese Funktionen geben die Anzahl der Zeichen zurück, die ausgegeben wurden (ohne abschließendes "\0" zum Terminieren von Strings). snprintf und vsnprintf schreiben maximal size Bytes (inklusive abschließendem '\0'), und geben -1 zurück, wenn die Ausgabe auf dieses Limit gekürzt werden musste. (Zumindest bis glibc 2.0.6. Seit glibc 2.1 folgen diese Funktionen dem C99-Standard und geben die Anzahl der Zeichen (ohne abschließendes "\0") zurück, die ausgegeben worden wären, wenn genug Platz vorhanden gewesen wäre.)

Der Formatstring ist eine Zeichenkette, die, so vorhanden, in ihrem initialen Shift-Zustand beginnt und endet. Der Formatstring setzt sich zusammen aus Null oder mehr Anweisungen: normale Zeichen (nicht %), welche unverändert zum Ausgabekanal kopiert werden; und Umwandlungsspezifikationen, welche jeweils null oder mehr Argumente fordern. Jede Umwandlungsspezifikation wird durch das Zeichen % eingeleitet und endet mit einem Umwandlungsspezifikator. Dazwischen können (in dieser Ordung) null oder mehr Flags, eine optionale minimale Feldbreite, eine optionale Genauigkeit und ein optionaler Längenmodifikator.

Die Argumente müssen (nach type promotion) genau zu den Umwandlungsspezifikatoren passen. Standardmäßig werden die Argumente in der Reihenfolge benutzt, in der sie angegeben sind, wobei jeder `*' und jeder Umwandlungsspezifikator das nächste Argument abfragt (und es ist ein Fehler, wenn nicht ausreichend Argumente gegeben sind). Man kann auch explizit angeben, welches Argument genommen wird, an jeder Stelle wo ein ein Argument erforderlich ist, indem man `%m$' anstelle von `*' schreibt, wobei die Dezimalzahl m die Position des gewünschten Arguments in der Argumentenliste angibt, beginnend mit 1. Damit sind

        printf("%*d", width, num);

und

        printf("%2$*1$d", width, num);

äquivalent. Der zweite Stil erlaubt wiederholte Referenzen auf das gleiche Argument. Der C99-Standard schließt den Stil mit `$' nicht mit ein, er stammt aus der Single Unix Specification. Wenn der Stil, der `$' benutzt, eingesetzt wird, muss er durchgehend für alle Umwandlungen, die ein Argument nehmen, und alle Breiten- und Genauigkeitsargumente verwendet werden, darf aber mit `%%', das kein Argument konsumiert, vermischt werden. Es darf keine Lücken in der Zahl der Argumente, die mit `$' spezifiziert werden, geben; zum Beispiel muss, wenn Argument 1 und 3 auftreten, auch Argument 2 irgendwo im Formatstring erwähnt werden.

Für einige numerische Umwandlungen wird ein Radixzeichen ("Dezimalkomma") oder ein Tausender-Gruppierungszeichen verwendet. Des tatsächlich benutzte Zeichen hängt vom LC_NUMERIC-Teil der Locale ab. 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.

Das Zeichen `%' wird von null oder mehr der folgenden Flags gefolgt:

#	gibt an, dass der Wert in eine ``alternative Form'' gewandelt werden soll. Bei der Umwandlung o wird das erste Zeichen der Ausgabe eine Null (indem `0' vorangestellt wird, wenn der Wert nicht schon Null war). Bei den Umwandlungen x und X wird einem Ergebnis ungleich Null der String `0x' (oder `0X' bei X) vorangestellt. Bei den Umwandlungen a, A, e, E, f, F, g und G enthält das Ergebnis immer einen Dezimaltrennzeichen, auch wenn ihm keine Ziffern folgen. (Normalerweise tritt ein Dezimaltrennzeichen nur in Ergebnissen auf, wenn ihm eine Ziffer folgt.) Bei den Umwandlungen g und G werden nachfolgende Nullen nicht aus dem Ergebnis entfernt, wie sie es normalerweise würden. Für andere Umwandlungen ist das Ergebis undefiniert.
amp;0	Auffüllen mit Nullen. Bei den Umwandlungen d, i, o, u, x, X, a, A, e, E, f, F, g und G wird der umgewandelte Wert links mit Nullen, nicht mit Leerzeichen aufgefüllt. Werden sowohl amp;0 als auch - angegeben, so wird amp;0 ignoriert. Wenn eine Genauigkeit bei einer numerischen Umwandlung (d, i, o, u, x und X), angegeben ist, wird das Flag amp;0 ignoriert. Für andere Umwandlungen ist das Ergebis undefiniert.
-	Linksbündige Ausgabe des umgewandelten Wertes an der Feldgrenze gesetzt wird. (Standard ist rechtsbündige Ausrichtung.) Außer bei der Umwandlung n wird der umgewandelte Wert rechts mit Leerzeichen aufgefüllt statt links mit Leerzeichen oder Nullen. Ein - übersteuert ein amp;0 falls beide angegeben sind.
` '	(ein Leerzeichen) gibt an, dass ein Leerzeichen vor einer positiven Zahl bleiben soll, die durch einen Vorzeichenwechsel entstanden ist.
+	gibt an, dass vor alle durch Vorzeichenwechel entstandenen Zahlen das Vorzeichen (`+' oder `-') gesetzt wird. Standardmäßig wird ein Vorzeichen nur für negative Zahlen verwendet. Ein + übersteuert ein Leerzeichen, falls beide angegeben sind.
Die obigen fünf Flags werden vom C-Standard definiert. Die SUSv2 spezifiziert ein weiteres Flag.
	Für dezimalen Umwandlungen (i, d, u, f, F, g, G) gibt an, dass die Ausgabe bei einem numerischen Argument guppiert werden soll, wenn die lokale Spracherweiterung dieses angibt. Beachte, dass viele Versionen vom gcc diese Option nicht parsen kann und stattdessen eine Warnung ausgeben. SUSv2 schließt %'F nicht mit ein.
glibc 2.2 fügt ein weiteres Flag hinzu.
I	Für dezimale Ganzzahlumwandlungen (i, d, u) benutzt die Ausgabe die alternativen Ausgabeziffern der Locale, wenn es solche gibt (zum Beispiel arabische Ziffern). Allerdings schließt die Bibliothek keine Locale-Definitionen mit ein, die outdigits definieren.

Eine optionale Dezimalzahl, die die minimale Feldbreite angibt. Wenn der umgewandelte Wert weniger Zeichen als die Feldbreite hat, wird er links mit Leerzeichen aufgefüllt (oder rechts, wenn das Flag für Linksbündigkeit gesetzt ist). Statt einer Dezimalzahl kann auch `*' oder `*m$' (für eine Dezimalzahl m) angegeben werden, um zu spezifizieren, dass die Feldbreite im nächsten (oder m-ten) Argument gegeben ist, welches den Type int haben muss. Eine negative Feldbreite wird als Flag `-' gefolgt von einer positiven Breite interpretiert. In keinem Fall resultiert eine nichtexistierende oder kleine Feldbreite im 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 (`amp;.') gefolgt von einer optionalen Zahl. Statt einer Dezimalzahl kann auch `*' oder `*m$' (für eine Dezimalzahl m) angegeben werden, um zu spezifizieren, dass die Genauigkeit im nächsten (oder m-ten) Argument gegeben ist, welches den Type int haben muss. Wenn die Zahl weggelassen wird oder es eine negative Zahle ist, wird eine Genauigkeit von Null angenommen. 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 eines Strings bei s und S.

Im folgenden steht "Ganzzahlumwandlung" für d, i, o, u, x oder X.

hh	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ signed char oder unsigned char, oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein signed-char-Argument.
h	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ short int oder unsigned short int, oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein short-int-Argument.
l	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ long int oder unsigned long int, oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein long-int-Argument, oder eine folgende c-Umwandlung entspricht einem Zeiger auf ein wchar_t-Argument,
ll	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ long long int oder unsigned long long int, oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein long-long-int-Argument.
L	Eine folgende a-, A-, e-, E-, f-, F-, g- oder G-Umwandlung entspricht einem long double-Argument. (C99 erlaubt %LF, aber SUSv2 nicht.)
q	(`quad'. Nur BSD 4.4 und Linux libc5. Nicht benutzen.) Dies ist ein Synonym für ll.
j	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ intmax_t oder uintmax_t.
z	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ size_t oder ssize_t. (Linux libc5 hat Z in dieser Bedeutung. Nicht benutzen.)
t	Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ ptrdiff_t.

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).

Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt. Die Umwandlungsspezifikatoren und ihre Bedeutung sind:

d,i	Das Argument int (oder eine entsprechende Variante) wird umgewandelt in eine vorzeichenbehaftete Dezimalzahl. Die Genauigkeit, sofern vorhanden, gibt die minimale Anzahl vor Ziffern an, die auftreten muss; wenn der umgewandelte Wert weniger Ziffern benötigt, wird er links mit Nullen aufgefüllt. Die voreingestellte Genauigkeit ist 1. Wird 0 mit einer expliziten Genauigkeit 0 gedruckt, so ist die Ausgabe leer.
o,u,x,X
	Das unsigned-int-Argument wird in eine vorzeichenlose Oktal- (o), Dezimal- (u), oder Hexadezimalzahl (x und X) umgewandelt. Die Buchstaben abcdef werden für Umwandlungen x benutzt; die Buchstaben ABCDEF für Umwandlungen X. Die Genauigkeit, sofern vorhanden, gibt die minimale Anzahl vor Ziffern an, die auftreten muss; wenn der umgewandelte Wert weniger Ziffern benötigt, wird er links mit Nullen aufgefüllt. Die voreingestellte Genauigkeit ist 1. Wird 0 mit einer expliziten Genauigkeit 0 gedruckt, so ist die Ausgabe leer.
e,E	Das Argument double wird gerundet und in das Format [-]damp;.ddde±dd umgewandelt, wobei eine Ziffer vor dem Dezimaltrennzeichen erscheint und die Anzahl der Ziffern dahinter der Genauigkeit entspricht; wenn die Genauigkeit fehlt, wird sie als 6 angenommen; wenn die Genauigkeit Null ist, erscheint kein Dezimaltrennzeichen. Eine Umwandlung E benutzt den Buchstaben E (in Gegensatz zu e), um den Exponenten einzuleiten. Der Exponent enthält immer mindestens zwei Ziffern; wenn der Wert Null ist, ist der Exponent 00.
f,F	Das Argument double wird gerundet und umgewandelt in dezimale Notation im Format [-]dddamp;.ddd, wobei die Anzahl der Ziffern hinter dem Dezimaltrennzeichen der Genauigkeit entspricht. Wenn die Genauigkeit fehlt, wird sie als 6 angenommen; wenn die Genauigkeit Null ist, erscheint kein Dezimaltrennzeichen. Wenn ein Dezimaltrennzeichen erscheint, befindet sich mindestens eine Ziffer davor.
(SUSv2 kennt F nicht und sagt, dass Zeichenkettenrepräsentationen für Unendlich und NaN (Not a Number - keine Zahl) vorhanden sein können. Der C99-Standard spezifiziert `[-]inf' oder `[-]infinity' für Unendlich, und eine Zeichenkette beginnend mit `nan' für NaN im Falle von f, und `[-]INF' oder `[-]INFINITY' oder `NAN' im Falle von F.)
g, G	Das Argument double wird umgewandelt in das Format f oder e (oder F oder E für die Umwandlung G). Die Genauigkeit gibt die Anzahl der signifikanten Stellen an. Wenn die Genauigkeit fehlt, werden 6 Ziffern zurückgegeben; wenn die Genauigkeit Null ist, wird sie als 1 angenommen. Form e wird benutzt, wenn der Exponent kleiner als -4 oder größer als oder gleich der Genauigkeit ist. Nachfolgende Nullen im Bruchteil werden entfernt; ein Dezimaltrennzeichen erscheint nur, wenn es von mindestens einer Ziffer gefolgt wird.
a,A	(C99; nicht in SUSv2) Für die Umwandlung a wird das double-Argument in hexadezimale Notation gebracht (unter Benutzung der Buchstaben abcdef) in der Form [-]0xhamp;.hhhhp±d; für A sind dagegen der Präfix 0X, die Buchstaben ABCDEF und das Exponententrennzeichen P. Vor dem Dezimaltrennzeichen ist eine hexadezimale Ziffer, die Anzahl der Stellen dahinter entspricht der Genauigkeit. Die standardmäßige Genauigkeit genügt für eine exakte Repräsentation des Wertes, wenn eine exakte Repräsentation zur Basis 2 existiert und ist sonstigenfalls groß genug, um Werte vom Typ double zu unterscheiden. Die Ziffer vor dem Dezimaltrennzeichen ist unspezifiziert für nichtnormalisierte Zahlen, und nicht Null, aber ansonsten unspezifiziert, für normalisierte Zahlen.
c	Wenn kein Modifikator l vorhanden ist, wird das Argument int umgewandelt in einen unsigned char und das resultierende Zeichen ausgegeben. Wenn ein l vorhanden ist, wird das wint_t-Argument (breites Zeichen) mit einem Ruf der Funktion wcrtomb zu einer Multibyte-Folge umgewandelt, mit der Konvertierung beginnend im initialen Zustand, und die resultierende Multibyte-Zeichenkette wird ausgegeben.
s	Wenn kein Modifikator l vorhanden ist, wird das Argument const char * erwartet als ein Zeiger auf ein Array vom Typ Character (Zeiger auf einen String). Zeichen aus diesem Array werden bis zu (aber nicht einschliesslich) des terminierenden NUL-Zeichens ausgegeben; wenn eine Genauigkeit angegeben ist, werden nicht mehr Zeichen als die angegebene Anzahl ausgegeben. Wenn eine Genauigkeit angegeben ist braucht kein Null-Zeichen vorhanden zu sein; wenn die Genauigkeit nicht angegeben ist oder größer als die Array-Größe ist, muss das Array ein beendendes Zeichen NUL enthalten. Wenn ein l vorhanden ist, wird das const-wchar_t-*-Argument als ein Zeiger auf ein Array von breiten Zeichen erwartet. Breite Zeichen aus dem Array werden zu Multibyte-Zeichen umgewandelt (jedes mit einem Ruf von wcrtomb, beginnend im initialen Zustand vor dem ersten breiten Zeichen), bis zu und einschließlich des terminierenden breiten NUL-Zeichens. Wenn eine Genauigkeit angegeben ist, werden nicht mehr Bytes als die angegebene Anzahl ausgegeben, aber es werden keine partiellen Multibyte-Zeichen ausgegeben. Man beachte, dass die Genauigkeit die Anzahl der Bytes, nicht der breiten Zeichen oder Bildschirmpositionen angibt. Das Array muss ein terminierendes breites NUL-Zeichen enthalten, wenn nicht eine Genauigkeit gegeben ist, die so klein ist, dass die Zahl der geschriebenen Bytes sie übersteigt, bevor das Ende des Arrays erreicht ist.
C	(Nicht in C99, aber in SUSv2.) Synonym für lc. Nicht benutzen.
S	(Nicht in C99, aber in SUSv2.) Synonym für ls. Nicht benutzen.
p	Das Zeiger-Argument void * wird hexadezimal ausgegeben (wie bei %#x oder %#lx).
n	Die Anzahl der bis hierhin ausgegebenen Zeichen wird in dem Integer gespeichert, der durch das Zeiger-Argument int * (bzw. Äquivalent) gegeben ist. Kein Argument wird umgewandelt.
%	Ein `%' wird ausgegeben. Kein Argument wird umgewandelt. Die komplette Umwandlungsspezifikation ist `%%'.

Um π 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 Strings sind:

#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
        weekday, month, day, hour, min);

Die meisten Länder benutzen 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 permutiert. Mit dem Wert

"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"

bekommt man dann `Sonntag, 3. Juli, 10:02'.

Um einen genügend großen String zu allozieren und in ihn zu schreiben (Code stimmt 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, ...) {
   /* Guess we need no more than 100 bytes. */
   int n, size = 100;
   char *p;
   va_list ap;
   if ((p = malloc (size)) == NULL)
      return NULL;
   while (1) {
      /* Try to print in the allocated space. */
      va_start(ap, fmt);
      n = vsnprintf (p, size, fmt, ap);
      va_end(ap);
      /* If that worked, return the string. */
      if (n > -1 && n < size)
         return p;
      /* Else try again with more space. */
      if (n > -1)    /* glibc 2.1 */
         size = n+1; /* precisely what is needed */
      else           /* glibc 2.0 */
         size *= 2;  /* twice the old size */
      if ((p = realloc (p, size)) == NULL)
         return NULL;
   }
}

Die Funktionen fprintf, printf, sprintf, vprintf, vfprintf, und vsprintf sind konform zu ANSI X3.159-1989 (`ANSI C') und ISO/IEC 9899:1999 (`ISO C99'). Die Funktionen snprintf und vsnprintf sind konform zu ISO/IEC 9899:1999.

Hinsichtlich des Rückgabewerts von snprintf widersprechen sich SUSv2 und der C99-Standard: wird snprintf mit size=0 gerufen, dann vereinbart SUSv2 einen unspezifizierten Rückgabewert kleiner als 1, während C99 es zulässt, dass str in diesem Fall NULL ist, und (wie immer) den Rückgabewert als die Anzahl der Zeichen, die, wäre der Ausgabestring groß genung gewesen, geschrieben worden wären, angibt.

Linux' libc5 kennt die fünf Standardflags von C und das '-Flag, Locale, %m$ und *m$. Sie kennt die Längenmodifikatoren h, l, L, Z und q, akzeptiert aber L und q sowohl für long double als auch für long long (das ist ein Bug). Sie erkennt FDOU nicht mehr, fügt aber einen neuen Umwandlungsspezifikator m hinzu, welcher strerror(errno) ausgibt.

glibc 2.0 fügt Umwandlungsspezifikatoren C und S hinzu.

glibc 2.1 fügt Längenmodifikatoren hh, j, t und z sowie Umwandlungsspezifikatoren a und A hinzu.

glibc 2.2 fügt den Umwandlungsspezifikatoren F mit der Bedeutung von C99 hinzu, sowie das Flag I.

Unix V7 defininiert die drei Routinen printf, fprintf, sprintf und hat das Flag `-', die Breite oder Genauigkeit `*', den Längenmodifikator l und die Umwandlungsspezifikatoren doxfegcsu sowie D, O, U, X als Synonyme für ld, lo, lu, lx. Das stimmt auch noch für BSD 2.9.1, aber BSD 2.10 hat die Flags `#', `+' und ` ' und erwähnt D, O, U, X nicht mehr. BSD 2.11 hat vprintf, vfprintf, vsprintf und warnt davor, D, O, U, X zu benutzen. BSD 4.3 Reno hat das Flag `0', die Längenmodifikatoren h nd L und die Umwandlungsspezifikatoren n, p, E, G, X (mit der heutigen Bedeutung) und rät von D, O, U ab. BSD 4.4 führt die Funktionen snprintf und vsnprintf und den Längenmodifikator q ein. FreeBSD hat auch die Funktionen asprintf und vasprintf, die einen Puffer, der groß genug für sprintf ist, alloziert.

Da sprintf und vsprintf einen beliebig langen String annehmen, muss der Rufer achtgeben, nicht den tatsächlich verfügbaren Platz zu überschreiten; dies ist oft unmöglich sicherzustellen. Man beachte, dass die Länge der Strings oft abhängig von der Locale und schwierig vorherzusagen sind. Stattdessen snprintf und vsnprintf benutzen (oder asprintf und vasprintf).

printf(fred); weist häufig auf einen Fehler hin, da fred das Zeichen `%' enthalten kann. Kommt fred von ungeprüfter Nutzereingabe, kann es %n enthalten und veranlasst print, in den Speicher zu schreiben und erzeugt damit ein Sicherheitsloch.