.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\"
.\" Earlier versions of this page influenced the present text.
.\" It was derived from a Berkeley page with version
.\"       @(#)printf.3    6.14 (Berkeley) 7/30/91
.\" converted for Linux by faith@cs.unc.edu, updated by
.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
.\"
.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
.\"
.\" Translation for said earlier version:
.\" Translated to German Mon May 27 16:00:00 1996 by Patrick Rother <krd@gulu.net>
.\" Modified Fri May 30 11:48:54 1996 by Martin Schulze (joey@infodrom.north.de)
.\" Modified Mon Jun 10 01:06:57 1996 by Martin Schulze (joey@linux.de)
.\" Modified Tue Dec 12 14:27:23 1996 by Martin Schulze (joey@linux.de)
.\" New approach for new version using old translations:
.\" Modified 15 Feb 2001 Michael Piefel <piefel@informatik.hu-berlin.de>
.\"
.TH PRINTF 3  "16. Oktober 2000" "GNU" "Bibliotheksfunktionen"
.SH "BEZEICHNUNG"
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf  \- formatierte Ausgabe
.SH "ÜBERSICHT"
.B #include <stdio.h>
.sp
.BI "int printf(const char *" format ", ...);"
.br
.BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
.br
.BI "int sprintf(char *" str ", const char *" format ", ...);"
.br
.BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
.br
.BI "int asprintf(char **" strp ", const char *" format ", ...);"
.br
.BI "int dprintf(int " d ", const char *" format ", ...);"
.sp
.B #include <stdarg.h>
.sp
.BI "int vprintf(const char *" format ", va_list " ap );
.br
.BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
.br
.BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
.br
.BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap );
.br
.BI "int vasprintf(char **" strp ", const char *" format ", va_list " ap );
.br
.BI "int vdprintf(int " d ", const char *" format ", va_list " ap );
.SH "BESCHREIBUNG"
Die Funktionenfamilie
.B printf
erzeugt Ausgaben in einen
.I format
wie unten beschrieben. Die Funktionen
.B printf
und
.B vprintf
schreiben ihre Ausgabe auf
.IR stdout ,
dem Standardausgabekanal;
.B fprintf
und
.B vfprintf
schreiben in den angegebenen Ausgabekanal
.IR stream ;
.BR sprintf ,
.BR snprintf ,
.BR vsprintf
und
.BR vsnprintf
schreiben in den String
.IR  str .
.PP
Die Funktionen
.BR vprintf ,
.BR vfprintf ,
.BR vsprintf ,
.B vsnprintf
sind äquivalent zu den Functionen
.BR printf ,
.BR fprintf ,
.B sprintf
bzw.
.BR snprintf ,
nur dass sie mit einer va_list statt einer variablen Zahl von Argumenten
aufgerufen werden. Diese Funktionen rufen das Makro
.I va_end
nicht auf. Daher ist der Wert von
.I ap
nach dem Aufruf undefiniert. Die Anwendung sollte nachher selbst
.I va_end(ap)
aufrufen.
.PP
Diese acht Funktionen schreiben die Ausgabe unter Kontrolle eines
.IR format "\-Strings,"
der angibt, wie die folgenden Argumente (oder Argumente, auf die mittels der
Möglichkeit der variablen Zahl von Argumenten von
.BR stdarg (3)
zugegriffen wird) für die Ausgabe konvertiert werden.
.SS "Rückgabewert"
Diese Funktionen geben die Anzahl der Zeichen zurück, die ausgegeben
wurden (ohne abschließendes "\e0" zum Terminieren von Strings).
.BR snprintf " und " vsnprintf
schreiben maximal
.I size
Bytes (inklusive abschließendem '\e0'), 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 "\e0")
zurück, die ausgegeben worden wären, wenn genug Platz vorhanden gewesen wäre.)
.SS "Format des Formatstrings"
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
.BR % ),
welche unverändert zum Ausgabekanal kopiert werden;
und Umwandlungsspezifikationen, welche jeweils null oder mehr Argumente 
fordern.  Jede Umwandlungsspezifikation wird durch das Zeichen
.BR % 
eingeleitet und endet mit einem
.IR Umwandlungsspezifikator .
Dazwischen können (in dieser Ordnung) null oder mehr
.IR Flags ,
eine optionale minimale
.IR Feldbreite ,
eine optionale
.I Genauigkeit
und ein optionaler
.IR Längenmodifikator .
.PP
Die Argumente müssen (nach \fItype promotion\fP) 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
.RS
.nf
	printf("%*d", width, num);
.fi
.RE
und
.RS
.nf
	printf("%2$*1$d", width, num);
.fi
.RE
ä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 \fISingle Unix Specification\fP.  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.
.PP
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
.RS
.nf
	printf("%'.2f", 1234567.89);
.fi
.RE
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.
.SS "Die Zeichen für die Flags"
Das Zeichen `%' wird von null oder mehr der folgenden Flags gefolgt:
.TP
.B #
gibt an, dass der Wert in eine ``alternative Form'' gewandelt werden soll.
Bei der Umwandlung 
.BR o
wird das erste Zeichen der Ausgabe eine Null (indem `0' vorangestellt wird, wenn
der Wert nicht schon Null war).  Bei den Umwandlungen
.B x
und
.B X
wird einem Ergebnis ungleich Null der String `0x' (oder `0X' bei
.BR X )
vorangestellt.  Bei den Umwandlungen
.BR a ,
.BR A ,
.BR e ,
.BR E ,
.BR f ,
.BR F ,
.B g
und
.B 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
.B g
und
.B G
werden nachfolgende Nullen nicht aus dem Ergebnis entfernt, wie sie es
normalerweise würden.
Für andere Umwandlungen ist das Ergebnis undefiniert.
.TP
.B \&0
Auffüllen mit Nullen.  Bei den Umwandlungen
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
.BR X ,
.BR a ,
.BR A ,
.BR e ,
.BR E ,
.BR f ,
.BR F ,
.B g
und
.B G
wird der umgewandelte Wert links mit Nullen, nicht mit Leerzeichen aufgefüllt.
Werden sowohl
.B \&0
als auch
.B \-
angegeben, so wird
.B \&0
ignoriert.
Wenn eine Genauigkeit bei einer numerischen Umwandlung
.BR "" ( d ,
.BR i ,
.BR o ,
.BR u ,
.B x
und
.BR X ),
angegeben ist, wird das Flag
.B \&0
ignoriert.
Für andere Umwandlungen ist das Ergebnis undefiniert.
.TP
.B \-
Linksbündige Ausgabe des umgewandelten Wertes an der Feldgrenze gesetzt wird.
(Standard ist rechtsbündige Ausrichtung.) Außer bei der Umwandlung
.B n
wird der umgewandelte Wert rechts mit Leerzeichen aufgefüllt statt links
mit Leerzeichen oder Nullen.  Ein
.B \-
übersteuert ein
.B \&0
falls beide angegeben sind.
.TP
.B ` '
(ein Leerzeichen) gibt an, dass ein Leerzeichen vor einer positiven Zahl
bleiben soll, die durch einen Vorzeichenwechsel entstanden ist.
.TP
.B +
gibt an, dass vor alle durch Vorzeichenwechsel entstandenen Zahlen das 
Vorzeichen (`+' oder `-') gesetzt wird.  Standardmäßig wird ein
Vorzeichen nur für negative Zahlen verwendet. Ein
.B +
übersteuert ein Leerzeichen, falls beide angegeben sind.
.PP
Die obigen fünf Flags werden vom C-Standard definiert. Die SUSv2 spezifiziert ein
weiteres Flag.
.TP
.B \'
Für dezimalen Umwandlungen
.BR "" ( i ,
.BR d ,
.BR u ,
.BR f ,
.BR F ,
.BR g ,
.BR G )
gibt an, dass die Ausgabe bei einem numerischen Argument guppiert
werden soll, wenn die lokale Spracherweiterung dieses angibt.
Beachte, dass viele Versionen vom
.B gcc
diese Option nicht parsen kann und stattdessen eine Warnung ausgeben.
SUSv2 schließt %'F nicht mit ein.
.PP
glibc 2.2 fügt ein weiteres Flag hinzu.
.TP
.B I
Für dezimale Ganzzahlumwandlungen
.BR "" ( i ,
.BR d ,
.BR 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
.B outdigits
definieren.
.\" See http://sources.redhat.com/ml/libc-alpha/2000-08/msg00230.html
.SS "Die Feldbreite"
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
.I 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.
.SS "Die Genauigkeit"
Eine optionale Genauigkeit in der Form eines Punkts (`\&.')  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
.I 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
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.B x
und
.B X
erscheinen, bzw. die Anzahl der Ziffern nach dem Dezimaltrennzeichen bei 
.BR a ,
.BR A ,
.BR e ,
.BR E ,
.B f
und
.B F
, die maximale Anzahl von signifikanten Ziffern bei
.B g
und
.B G
, oder die maximale Anzahl von auszugebenden Zeichen eines Strings bei
.B s
und
.BR S .
.SS "Der Längenmodifikator"
Im Folgenden steht "Ganzzahlumwandlung" für
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x
oder
.BR X .
.TP
.B hh
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.I signed char
oder
.IR "unsigned char" ,
oder eine folgende
.BR n -Umwandlung
entspricht einem Zeiger auf ein
.IR signed - char -Argument.
.TP
.B h
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.I short int
oder
.IR "unsigned short int" ,
oder eine folgende
.BR n -Umwandlung
entspricht einem Zeiger auf ein
.IR short - int -Argument.
.TP
.B l
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.I long int
oder
.IR "unsigned long int",
oder eine folgende
.BR n -Umwandlung
entspricht einem Zeiger auf ein
.IR long - int -Argument,
oder eine folgende
.BR c -Umwandlung
entspricht einem Zeiger auf ein
.IR wchar_t -Argument,
.TP
.B ll
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.I long long int
oder
.IR "unsigned long long int" ,
oder eine folgende
.BR n -Umwandlung
entspricht einem Zeiger auf ein
.IR long - long - int -Argument.
.TP
.B L
Eine folgende
.BR a -,
.BR A -,
.BR e -,
.BR E -,
.BR f -,
.BR F -,
.BR g -
oder
.BR G -Umwandlung
entspricht einem
.IR "long double" -Argument.
(C99 erlaubt %LF, aber SUSv2 nicht.)
.TP
.B q
(`quad'. Nur BSD 4.4 und Linux libc5. Nicht benutzen.) Dies ist ein Synonym für
.BR ll .
.TP
.B j
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.I intmax_t
oder
.IR uintmax_t .
.TP
.B z
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.I size_t
oder
.IR ssize_t.
(Linux libc5 hat
.B Z
in dieser Bedeutung. Nicht benutzen.)
.TP
.B t
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
.IR ptrdiff_t .
.PP
SUSv2 kennt nur die Längenmodifikatoren
.B h
(in
.BR hd ,
.BR hi ,
.BR ho ,
.BR hx ,
.BR hX ,
.BR hn )
und
.B l
(in
.BR ld ,
.BR li ,
.BR lo ,
.BR lx ,
.BR lX ,
.BR ln ,
.BR lc ,
.BR ls )
und
.B L
(in
.BR Le ,
.BR LE ,
.BR Lf ,
.BR Lg ,
.BR LG ).
.SS "Der Umwandlungsspezifikator"
Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt.
Die Umwandlungsspezifikatoren und ihre Bedeutung sind:
.TP
.BR d , i
Das Argument 
.I 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.
.TP
.BR o , u , x , X
Das
.IR unsigned - int -Argument
wird in eine vorzeichenlose Oktal-
.BR "" ( o ),
Dezimal-
.BR "" ( u ),
oder Hexadezimalzahl
.BR "" ( x
und
.BR X )
umgewandelt. Die Buchstaben 
.B abcdef
werden für Umwandlungen
.B x
benutzt; die Buchstaben
.B ABCDEF
für Umwandlungen
.BR 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.
.TP
.BR e , E
Das Argument 
.I double
wird gerundet und in das Format
.if \w'\*(Pm'=0 .ds Pm ±
.BR "" [\-]d \&. ddd e \\*(Pmdd
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 
.B E
benutzt den Buchstaben 
.B E
(in Gegensatz zu
.BR e ),
um den Exponenten einzuleiten.  Der Exponent enthält immer mindestens zwei 
Ziffern; wenn der Wert Null ist, ist der Exponent 00.
.TP
.BR f , F
Das Argument
.I double
wird gerundet und umgewandelt in dezimale Notation im Format
.BR "" [-]ddd \&. 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.
.PP
(SUSv2 kennt
.B 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
.BR f ,
und `[-]INF' oder `[-]INFINITY' oder `NAN' im Falle von
.BR F .)
.TP
.B g , G
Das Argument
.I double
wird umgewandelt in das Format
.B f
oder
.B e
(oder
.B F
oder
.B E
für die Umwandlung
.BR 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
.B 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.
.TP
.BR a , A
(C99; nicht in SUSv2) Für die Umwandlung
.B a
wird das
.IR double -Argument
in hexadezimale Notation gebracht (unter Benutzung der Buchstaben abcdef) in der Form
.BR "" [-] 0x h \&. hhhh p \\*(Pmd;
für
.B A
sind dagegen der Präfix
.BR 0X,
die Buchstaben ABCDEF und das Exponententrennzeichen
.BR 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
.I double
zu unterscheiden. Die Ziffer vor dem Dezimaltrennzeichen ist unspezifiziert für
nichtnormalisierte Zahlen, und nicht Null, aber ansonsten unspezifiziert, für
normalisierte Zahlen.
.TP
.B c
Wenn kein Modifikator
.B l
vorhanden ist, wird das Argument
.I int
umgewandelt in einen 
.I "unsigned char"
und das resultierende Zeichen ausgegeben.
Wenn ein
.B l
vorhanden ist, wird das
.IR wint_t -Argument
(breites Zeichen) mit einem Ruf der Funktion
.B wcrtomb
zu einer Multibyte-Folge umgewandelt, mit der Konvertierung beginnend im
initialen Zustand, und die resultierende Multibyte-Zeichenkette wird ausgegeben.
.TP
.B s
Wenn kein Modifikator
.B l
vorhanden ist, wird das Argument
.I "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 
einschließlich) des terminierenden
.BR 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
.B NUL
enthalten.
Wenn ein
.B l
vorhanden ist, wird das
.IR 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
.BR wcrtomb,
beginnend im initialen Zustand vor dem ersten breiten Zeichen), bis zu und
einschließlich des terminierenden breiten
.BR 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
.IR Bytes ,
nicht der
.I "breiten Zeichen"
oder
.I Bildschirmpositionen
angibt. Das Array muss ein terminierendes breites
.BR 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.
.TP
.B C
(Nicht in C99, aber in SUSv2.)
Synonym für
.BR lc .
Nicht benutzen.
.TP
.B S
(Nicht in C99, aber in SUSv2.)
Synonym für
.BR ls .
Nicht benutzen.
.TP
.B p
Das Zeiger-Argument
.I "void *"
wird hexadezimal ausgegeben (wie bei
.B %#x
oder
.BR  %#lx ).
.TP
.B n
Die Anzahl der bis hierhin ausgegebenen Zeichen wird in dem Integer
gespeichert, der durch das Zeiger-Argument
.I "int *"
(bzw. Äquivalent) gegeben ist.  Kein Argument wird umgewandelt.
.TP
.B %
Ein `%' wird ausgegeben.  Kein Argument wird umgewandelt.  Die komplette
Umwandlungsspezifikation ist `%%'.
.PP
.SH BEISPIELE
.br
.if \w'\*(Pi'=0 .ds Pi pi
Um \*(Pi mit fünf Dezimalstellen auszugeben:
.RS
.nf
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
.fi
.RE
.PP
Um Datum und Zeit in der Form `Sunday, July 3, 10:02' auszugeben,
wobei
.I weekday
und
.I month
Zeiger auf Strings sind:
.RS
.nf
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
	weekday, month, day, hour, min);
.fi
.RE
.PP
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:
.RS
.nf
#include <stdio.h>
fprintf(stdout, format,
	weekday, month, day, hour, min);
.fi
.RE
wobei
.I format
von der Locale abhängt, und möglicherweise die Argumente permutiert. Mit dem
Wert
.RS
.nf
"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
.fi
.RE
bekommt man dann `Sonntag, 3. Juli, 10:02'.
.PP
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):
.RS
.nf
#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;
   }
}
.fi
.RE
.SH "SIEHE AUCH"
.BR printf (1),
.BR wcrtomb (3),
.BR wprintf (3),
.BR scanf (3),
.BR locale (5).
.SH "STANDARDS"
Die Funktionen
.BR fprintf ,
.BR printf ,
.BR sprintf ,
.BR vprintf ,
.BR vfprintf ,
und
.B vsprintf
sind konform zu ANSI X3.159-1989 (`ANSI C') und ISO/IEC 9899:1999 (`ISO C99').
Die Funktionen
.B snprintf
und
.B vsnprintf
sind konform zu ISO/IEC 9899:1999.
.PP
Hinsichtlich des Rückgabewerts von
.B snprintf
widersprechen sich SUSv2 und der C99-Standard: wird
.B snprintf
mit
.IR size =0
gerufen, dann vereinbart SUSv2 einen unspezifizierten Rückgabewert kleiner als
1, während C99 es zulässt, dass
.I str
in diesem Fall NULL ist, und (wie immer) den Rückgabewert als die Anzahl der
Zeichen, die, wäre der Ausgabestring groß genug gewesen, geschrieben worden
wären, angibt.
.PP
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 \fIlong double\fP als auch für \fIlong long\fP (das ist ein
Bug). Sie erkennt FDOU nicht mehr, fügt aber einen neuen Umwandlungsspezifikator
.B m
hinzu, welcher
.I strerror(errno)
ausgibt.
.PP
glibc 2.0 fügt Umwandlungsspezifikatoren C und S hinzu.
.PP
glibc 2.1 fügt Längenmodifikatoren hh, j, t und z sowie
Umwandlungsspezifikatoren a und A hinzu.
.PP
glibc 2.2 fügt den Umwandlungsspezifikatoren F mit der Bedeutung von C99 hinzu,
sowie das Flag I.
.SH "GESCHICHTE"
Unix V7 defininiert die drei Routinen
.BR printf ,
.BR fprintf ,
.B 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
.BR vprintf ,
.BR vfprintf ,
.B 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
.B snprintf
und
.B vsnprintf
und den Längenmodifikator q ein.
FreeBSD hat auch die Funktionen
.I asprintf
und
.IR vasprintf ,
die einen Puffer, der groß genug für
.B sprintf
ist, alloziert.
.SH BUGS
Da
.B sprintf
und
.B vsprintf
einen beliebig langen String annehmen, muss der Rufer Acht geben, 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
.B snprintf
und
.B vsnprintf
benutzen (oder
.B asprintf
und
.BR vasprintf ).
.PP Code wie
.BI printf( fred );
weist häufig auf einen Fehler hin, da
.I fred
das Zeichen `%' enthalten kann. Kommt
.I fred
von ungeprüfter Nutzereingabe, kann es %n enthalten und veranlasst
.BR print ,
in den Speicher zu schreiben und erzeugt damit ein Sicherheitsloch.