Hauptindex | Abschnitt 3 | English | 日本語 | Optionen |
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);
Die Funktionen vprintf, vfprintf, vsprintf, vsnprintf sind äquivalent zu den Functionen printf, fprintf, 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 undefiniert. Die Anwendung sollte nachher selbst va_end(ap) aufrufen.
Diese acht Funktionen schreiben die Ausgabe unter Kontrolle eines format-Strings, der 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.
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
undprintf("%*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.printf("%2$*1$d", width, num);
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
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.printf("%'.2f", 1234567.89);
# | 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. |
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. |
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 `%%'. |
#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:
wobei format von der Locale abhängt, und möglicherweise die Argumente permutiert. Mit dem Wert#include <stdio.h> fprintf(stdout, format, weekday, month, day, hour, min);
bekommt man dann `Sonntag, 3. Juli, 10:02'."%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
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; } }
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.
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.
16. Oktober 2000 | PRINTF (3) | GNU |
Hauptindex | Abschnitt 3 | English | 日本語 | Optionen |
Bitte richten Sie Ihre Kommentare zu diesem Handbuch Seite Service, Ben Bullock. Privacy policy.