.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)printf.3	6.14 (Berkeley) 7/30/91
.\"
.\" Converted for Linux, Mon Nov 29 12:06:07 1993, faith@cs.unc.edu
.\"
.\" Modified to resemble the GNU libio setup used in the Linux libc
.\" used in versions 4.x (x>4) and 5, Helmut.Geyer@iwr.uni-heidelberg.de
.\"
.\" Added [v]snprintf, 1996/01/28, agulbra@troll.no
.\"
.\" Translated to German Mon May 27 16:00:00 1996 by Patrick Rother (krd@burn.rhein-ruhr.de)
.\" 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)
.\"
.TH PRINTF 3  "31. Mai 1996" "BSD" "Bibliotheksfunktionen"
.SH BEZEICHNUNG
printf, fprintf, sprintf, vprintf, vfprintf, vsprintf \- 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 ", ...);"
.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 ", char *" format ", va_list " ap );
.SH BESCHREIBUNG
Die Funktionenfamilie
.B printf
erzeugt Ausgaben in einen
.I format
wie unten beschrieben.
.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 ,
und
.BR vsprintf
schreiben in den String
.IR  str .

Diese Funktionen schreiben die Ausgabe unter Kontrolle eines
.IR format "\-Strings"
der angibt, wie die folgenden Argumente (oder Argumente, auf die ber 
.BR stdarg (3)
zugegriffen wird) fr die Ausgabe konvertiert werden.

Diese Funktionen geben die Anzahl der Zeichen zurck, die ausgegeben
wurden (ohne abschlieendes "\e0" zum Terminieren von Strings).
.BR snprintf " und " vsnprintf
schreiben maximal
.I size
Bytes (inklusive abschlieendem '\e0'), und geben \-1 zurck, wenn
die Ausgabe auf dieses Limit gekrzt werden mute.

.PP
Der Format-String setzt sich zusammen aus Null oder mehr Anweisungen: normale
Zeichen (nicht
.BR % ),
welche unverndert zum Ausgabekanal kopiert werden;
und Umwandlungsspezifikationen, welche jeweils Null oder mehr Argumente 
fordern.  Jede Umwandlungsspezifikation wird durch das Zeichen
.BR % 
eingeleitet.
Die Argumente mssen genau zu den Umwandlungsspezifikatoren passen.
Nach dem
.BR %
erscheint das folgende nacheinander:
.TP
.B \(bu
Null oder mehr der folgenden Flags:
.RS
.TP
.B #
gibt an, da der Wert in eine ``alternative Form'' gewandelt werden soll.
Bei den Umwandlungen
.BR c ,
.BR d ,
.BR i ,
.BR n ,
.BR p ,
.BR s ,
und
.BR u
hat diese Option keine Einflu.  Bei der Umwandlung 
.BR o
wird die Genauigkeit der Zahl erhht um zu erzwingen, da das erste Zeichen
des Ausgabestrings eine Null ist (ausser wenn ein Null-Wert ausgegeben
wird mit einer expliziten Genauigkeit von Null).
Bei den Umwandlungen
.B x
und
.B X
wird einem Ergebnis ungleich Null der String `0x' (oder `0X' bei
.B X
) vorangestellt.  Bei den Umwandlungen
.BR e ,
.BR E ,
.BR f ,
.BR g ,
und
.B G
enthlt das Ergebnis immer einen Dezimalpunkt, auch wenn ihm keine Ziffern
folgen.  (Normalerweise tritt ein Dezimalpunkt 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 wrden.
.TP
.B \&0
Auffllen mit Nullen.  Bei allen Umwandlungen auer
.BR n
wird der umgewandelte Wert links mit Nullen, nicht mit Leerzeichen aufgefllt.
Wenn eine Genauigkeit bei einer numerischen Umwandlung
.BR "" ( d ,
.BR i ,
.BR o ,
.BR u ,
.BR i ,
.BR x ,
und
.BR X ),
angegeben ist, wird das Flag
.B \&0
ignoriert.
.TP
.B \-
(ein negatives Feldgrenflag) zeigt an, da der umgewandelte Wert linksbndig
zur Feldgrenze gesetzt wird.  Auer bei der Umwandlung
.B n
wird der umgewandelte Wert rechts mit Leerzeichen aufgefllt statt links
mit Nullen.  Ein
.B \-
bersteuert ein
.B \&0
falls beide angegeben sind.
.TP
.B \' \'
(ein Leerzeichen) gibt an, da ein Leerzeichen vor einer positiven Zahl
bleiben soll, die durch einen Vorzeichenwechsel entstanden ist.
.BR "" ( d ,
.BR e ,
.BR E ,
.BR f ,
.BR g ,
.BR G ,
oder
.BR i ).
.TP
.B +
gibt an, da vor alle durch Vorzeichenwechel entstandenen Zahlen das 
Vorzeichen gesetzt wird.  Ein
.B +
bersteuert ein Leerzeichen, falls beide angegeben sind.
.B '
gibt an, da die Ausgabe bei einem numerischen Argument guppiert
werden soll, wenn die lokale Spracherweiterung dieses angibt.
Beachte, da viele Versionen vom
.B gcc
diese Option nicht parsen kann und stattdessen eine Warnung ausgeben.
.RE
.TP
.B \(bu
Eine optionale Dezimalzahl, die die minimale Feldlnge angibt.  Wenn der
umgewandelte Wert weniger Zeichen als die Feldlnge hat, wird er links mit
Leerzeichen aufgefllt (oder rechts, wenn das Flag fr Linksbndigkeit 
gesetzt ist).
.TP
.B \(bu
Eine optionale Genauigkeit in der Form eines Punkts (`\&.')  gefolgt von einer
optionalen Zahl.  Wenn die Zahl weggelassen wird 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 ,
.BR x ,
und
.B X
erscheinen, bzw. die Anzahl der Ziffern nach dem Dezimalpunkt bei 
.BR e ,
.BR E ,
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 .
.TP
.B \(bu
Das optionale Zeichen
.BR h ,
das angibt, da eine folgende Umwandlung
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
oder
.BR X
zu einem Argument
.I short int
oder
.I unsigned short int
gehrt, oder da eine folgende Umwandlung
.B n
zu einem Zeiger auf ein Argument
.I short int
gehrt.
.TP
.B \(bu
Das optionale Zeichen
.B l
(el), das angibt, da eine folgende Umwandlung
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
oder
.BR X
auf einen Zeiger auf ein Argument
.I long int
oder
.I unsigned long int
angewendet wird, oder da die Umwandlung 
.B n
zu einem Zeiger auf ein Argument
.I long int
gehrt.  Linux untersttzt eine nicht-ANSI kompatible Benutzung von
zwei
.B l
Flags, die ein Synonym fr
.B q
oer
.B L
sind.  Daher kann
.B ll
in Verbindung mit Realzahl-Konvertierungen benutzt werden.  Von dieser
Verwendung wird trotzdem strikt abgeraten.
.TP
.B \(bu
Das Zeichen
.BR L ,
da angibt, da eine folgende Umwandlung
.BR e ,
.BR E ,
.BR f ,
.BR g ,
oder
.B G
zu einem Argument
.I long double
gehrt.  Beachte, da
.I long long
nicht in
.I ANSI C
spezifiziert ist und daher nicht portabel fr alle Architekturen ist.
.B \(bu
Das optionale Zeichen
.BR q .
Dieses is quivalent zu 
.BR L .
Siehe Abschnitte STANDARDS und BUGS fr Kommentare zur Benutzung von
.BR ll ,
.BR L ,
und
.BR q.
.TP
.B \(bu
Ein Zeichen
.BR Z ,
das angibt, da die folgende Ganzzahl
.BR "" ( d ,
.BR i ,
.BR o ,
.BR u ,
.BR i ,
.BR x ,
und
.BR X )
Umwandlung mit einem Argument vom Typ
.I size_t
zusammenhngt.
.TP
.B \(bu
Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt.
.PP
Eine Feldlnge oder Genauigkeit, oder beides, darf durch Einen Stern `*'
anstelle einer Zahl angegeben werden.  In diesem Fall enthlt ein Argument
.I int
die Feldgre oder Genauigkeit.  Eine negative Feldgre wird als ein 
Linksbndigkeitsflag gefolgt von einer positiven Feldgre aufgefat; eine
negative Genauigkeit wird behandelt, als wenn sie fehlen wrde.
.PP
Die Umwandlungsspezifikatoren und ihre Bedeutung:
.TP
.B diouxX
Das Argument 
.I int
(oder eine entsprechende Variante) wird umgewandelt in eine 
vorzeichenbehaftete Dezimalzahl
.BR "" ( d
und
.BR i ),
eine vorzeichenlose oktal-
.BR "" ( o ),
Dezimal-
.BR "" ( u ),
oder Hexadezimalzahl
.BR "" ( x
und
.BR X ).
Die Buchstaben 
.B abcdef
werden fr Umwandlungen
.B x
benutzt; die Buchstaben
.B ABCDEF
fr Umwandlungen
.BR X .
Die Genauigkeit, sofern vorhanden, gibt die minimale Anzahl vor Ziffern an,
die Auftreten mu; wenn der umgewandelte Wert weniger Ziffern bentigt wird er
links mit Nullen aufgefllt.
.TP
.B DOU
Das Argument 
.I long int
wird in eine vorzeichenbehaftete Dezimalzahl, vorzeichenlose Oktal- oder 
Dezimalzahl umgewandelt, als wenn das Format 
.BR ld ,
.BR lo ,
beziehungsweise
.B lu
wre.  Diese Umwandlungszeichen werden mibilligt und werden eventuell
verschwinden.
.TP
.B eE
Das Argument 
.I double
wird gerundet und umgewandelt in das Format
.BR "" [\-]d \&. ddd e \\*(Pmdd,
wobei eine Ziffer vor dem Dezimalpunkt 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 Dezimalpunkt.
Eine Umwandlung 
.B E
benutzt den Buchstaben 
.B E
(in Gegensatz zu
.BR e )
um den Exponenten einzuleiten.  Der Exponent enthlt immer mindestens zwei 
Ziffern; wenn der Wert Null ist ist der Exponent 00.
.TP
.B f
Das Argument
.I double
wird gerundet und umgewandelt in dezimale Notation im Format
.BR "" [-]ddd \&. ddd,
wobei die Anzahl der Ziffern hinter dem Dezimalpunkt der Genauigkeit entspricht.
Wenn die Genauigkeit fehlt wird sie als 6 angenommen; wenn die Genauigkeit Null 
ist erscheint kein Dezimalpunkt.
Wenn ein Dezimalpunkt erscheint befindet sich mindestens eine Ziffer davor.
.TP
.B g
Das Argument
.I double
wird umgewandelt in das Format
.B f
oder
.B e
(oder
.B E
fr die Umwandlung
.BR G ).
Die Genauigkeit gibt die Anzahl der signifikanten Stellen an.
Wenn die Genauigkeit fehlt werden 6 Ziffern zurckgegeben; wenn die Genauigkeit
Null ist wird sie als 1 angenommen.
Form
.B e
wird benutzt wenn der Exponent kleiner als \-4 oder grer als oder gleich
der Genauigkeit ist.  Nachfolgende Nullen im Bruchteil werden entfernt; ein
Dezialpunkt erscheint nur wenn er von mindestens einer Ziffer gefolgt wird.
.TP
.B c
Das Argument
.I int
wird umgewandelt in ein
.IR "unsigned char" ,
und das resultierende Zeichen wird ausgegeben.
.TP
.B s
Das Argument
.IR "" `` "char *" ''
wird erwartet als ein Zeiger auf ein Array vom Typ Character (Zeiger
auf einen String).  Zeichen auf diesem Array werden bis zu (aber nicht 
einschliesslich) 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 grer als die Array-Gre ist,
mu das Array ein beendendes Zeichen
.B NUL
enthlaten.
.TP
.B p
Das Zeiger-Argument
.IR "" `` "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
.IR "" `` "int *" ''
(bzw. quivalent) gegeben ist.  Kein Argument wird umgewandelt.
.TP
.B %
Ein `%' wird ausgegeben.  Kein Argument wird umgewandelt.  Die komplette
Umwandlungsspezifikation ist `%%'.
.PP
In keinem Fall fhrt eine nicht existierende oder kleine Feldgre zum
Abschneiden des Feldes; wenn das Ergebnis lnger als die Feldgre ist
wird das Feld erweitert um das Ergebnis aufzunehmen.
.PP
.SH BEISPIELE
.br
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
Um \*(Pi mit fnf Dezimalstellen auszugeben:
.RS
.nf
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
.fi
.RE
.PP
Um einen 128 byte - String zu belegen und in diesen zu schreiben:
.RS
.nf
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *newfmt(const char *fmt, ...)
{
		char *p;
		va_list ap;
		if ((p = malloc(128)) == NULL)
			return (NULL);
		va_start(ap, fmt);
		(void) vsnprintf(p, 128, fmt, ap);
		va_end(ap);
		return (p);
}
.fi
.RE
.SH "SIEHE AUCH"
.BR printf (1),
.BR scanf (3).
.SH STANDARDS
Die Funktionen
.BR fprintf ,
.BR printf ,
.BR sprintf ,
.BR vprintf ,
.BR vfprintf ,
und
.B vsprintf
sind konform zu ANSI C3.159-1989 (``ANSI C'').
Das
.BR q "\-Flag"
ist die
.IR "BSD 4.4" \-Notation
fr
.IR "long long" ,
whrend
.B ll
oder die Bedeutung von
.B L
eine Ganzzahlkonvertierung in der GNU-Notation ist.

Die Linux-Version dieser Funktionen basiert auf der
.I GNU
.I libio
Bibliothek.  Beachten Sie auch die
.IR info \-Dokumentation
der
.I GNU
.I libc (glibc-1.08)
fr eine genauere Beschreibung.
.SH BUGS
Einige Fliekommaumwandlungen erzeugen Speicherverluste unter Linux.

Die Umwandlungsformate 
.BR \&%D ,
.BR \&%O ,
und
.B %U
sind nicht standard und werden nur aus Kompatibilittsgrnden zur Verfgung 
gestellt.  Sie knnen unter Linux fehlen.

Alle Funktionen sind voll ANSI C3.159-1989 konform, aber bieten die
zustzlichen Flags
.BR q ,
.B Z
und
.B '
genauso wie ein zustzliches Verhalten der Flags
.B L
und
.BR l .
Letzteres darf als Bug betrachtet werden, da es das Verhalten des
Flags wie in ANSI C3.159-1989 definiert verndert.

Der Effekt, das Format
.B %p
mit Nullen aufzufllen (entweder durch das Flag
.B 0
oder durch Angabe einer Genauigkeit), und der geringe Effekt (es gibt keinen)
des Flags
.B #
bei den Umwandlungen
.B %n
und
.B %p
, sowie andere unsinnige Kombinationen wie
.BR %Ld ,
sind nicht standard und sollten vermieden werden.

Einige Kombinationen von Flags, die in 
.I ANSI C
definiert sind, geben keinen Sinn (z.B.
.BR "%Ld" ).
Whrend sie unter Linux ein wohl-definiertes Verhalten an den Tag
legen, mu es bei anderen Architekturen nicht der Fall sein.  Daher
ist es normalerweise keine Flags zu benutzen, die nicht in
.I ANSI C
definiert sind, z.B. die Verwendung von
.B q
anstelle von
.B L
in Verbindung mit
.B diouxX
oder
.BR ll .

Der Gebrauch von
.B q
ist nicht der gleiche wie in
.IR "BSD 4.4" ,
da er in Realzahl-Konvertierungen gleichbedeutend zu 
.B L
benutzt werden kann.

Da
.B sprintf
und
.B vsprintf
einen unendlich langen Sting annehmen mu der Aufrufer aufpassen, nicht den
zur Verfgung stehenden Platz zu berschreiten; dies sicherzustellen ist
oft nicht mglich.