printf(3S) printf(3S)
NAME
printf, fprintf, sprintf - Formatierte Ausgabe
SYNTAX
#include <stdio.h>
int printf(const char *format, .../* args */);
int fprintf(FILE *stream, const char *format, .../* args */);
int sprintf(char *s, const char *format, .../* args */);
BESCHREIBUNG
printf() schreibt auf die Standardausgabe stdout.
fprintf() schreibt in die angegebene Ausgabedatei stream.
sprintf() schreibt mit abschließendem Nullbyte in die auf den Spei-
cherplatz s folgenden Bytes.
Der Benutzer ist dafür verantwortlich, daß ausreichender Speicherplatz
zur Verfügung steht. Jede Funktion gibt die Anzahl der übertragenen
Zeichen (ausschließlich \0 im Fall von sprintf()) oder, wenn ein Aus-
gabefehler aufgetreten ist, einen negativen Wert zurück.
Diese Funktionen wandeln ihre Argumente args um, formatieren sie und
geben sie in der durch format angegebenen Form aus. format ist ein
String, der drei Objekttypen enthalten kann:
1. Normale Zeichen, die einfach in den Ausgabe-Stream kopiert werden
2. Escape-Folgen, die nichtgrafische Zeichen darstellen
3. Umwandlungsanweisungen
Die folgenden Escape-Folgen erzeugen die angegebene Aktion auf Gerä-
ten, die diese Aktion ausführen können:
\a Alarm. Darstellung des BEL-Zeichens: ein Ton wird ausgegeben.
\b Backspace. Darstellung des BS-Zeichens: Die Ausgabeposition wird
ein Zeichen vor die aktuelle Position verschoben, es sei denn,
die aktuelle Position ist der Zeilenanfang.
\f Form Feed. Darstellung des FF-Zeichens: Die Ausgabeposition wird
an den Anfang der nächsten logischen Seite geschoben.
\n New Line. Darstellung des NL-Zeichens: Die Ausgabeposition wird
an den Anfang der nächsten Zeile geschoben.
\r Return. Darstellung des CR-Zeichens: Die Ausgabeposition wird an
den Anfang der aktuellen Zeile geschoben.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
\t Horizontaler Tabulator. Darstellung des TAB-Zeichens: Die Ausga-
beposition wird auf die Position des nächsten horizontalen Tabu-
lators der aktuellen Zeile geschoben.
\v Vertikaler Tabulator. Darstellung des VT-Zeichens: Die Ausgabepo-
sition wird auf die Position des nächsten vertikalen Tabulators
der aktuellen Zeile geschoben.
\? Ausgabe des Fragezeichens
\\ Ausgabe des Backslashes (\)
\' Ausgabe des einfachen Hochkommas
\" Ausgabe des doppelten Hochkommas
\octalcode
Ausgabe eines im Oktalcode eingegebenen Zeichens im ASCII-Code
\xhexadecimalcode
Ausgabe eines im Hexadezimalcode eingegebenen Zeichens im ASCII-
Code
Beispiel: \100 (okt.) oder \x40 (hex.) ergeben beide dasselbe
Zeichen @ im ASCII-Code.
Umwandlungsanweisungen
Jede Umwandlungsanweisung wird durch das Zeichen % eingeleitet. Hinter
dem Zeichen % erscheinen nacheinander folgende Elemente:
- Ein optionales Feld, das aus einer Folge von Dezimalzahlen besteht,
denen ein $ folgt. Dieses Feld gibt die nächsten Argumente an, die
umgewandelt werden sollen. Wenn dieses Feld nicht vorhanden ist,
werden die Argumente verwendet, die den letzten umgewandelten Argu-
menten folgen.
- Eine optionale Folge von Dezimalzahlen zur Angabe einer Mindest-
feldgröße. Wenn der umgewandelte Wert weniger Zeichen als die Feld-
größe hat, wird er links (oder rechts, wenn das unten beschriebene
Flag zur linksbündigen Ausrichtung angegeben wurde) bis zur Feld-
größe aufgefüllt.
- Eine optionale Genauigkeitsangabe, die die Mindestanzahl der Zif-
fern angibt, die bei den Umwandlungen d, i, o, u, x oder X erschei-
nen sollen (das Feld wird mit führenden Nullen aufgefüllt), die
Anzahl von Ziffern, die nach dem Dezimalpunkt für die Umwandlungen
e, E und f erscheinen sollen, die maximale Anzahl signifikanter
Ziffern für die Umwandlungen g und G, oder die maximale Anzahl von
Zeichen, die aus einem String bei der Umwandlung s ausgegeben wer-
den sollen. Die Genauigkeitsangabe ist ein Punkt, gefolgt von einer
Folge aus Dezimalzahlen. Eine leere Ziffernfolge wird als Null
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
behandelt. Ein durch die Genauigkeitsangabe festgelegtes Auffüllen
überschreibt das Auffüllen, das durch die Feldgröße festgelegt
wird.
- Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt.
Eine Feldgröße oder Genauigkeitsangabe kann statt mit einer Ziffern-
folge auch durch einen Stern (*) angezeigt werden. In diesem Fall gibt
ein ganzzahliges Argument die Feldgröße oder Genauigkeit an. Das umzu-
wandelnde Argument wird solange nicht gelesen, bis das entsprechende
Umwandlungszeichen gefunden ist. Argumente, die Feldgröße oder Genau-
igkeit angeben, müssen also vor dem umzuwandelnden Argument stehen.
Wenn das Argument für die Genauigkeit negativ ist, wird es in Null
geändert. Ein negatives Argument für die Feldgröße wird als Flag "-"
betrachtet, dem eine positive Feldgröße folgt.
In Format-Strings, die die Form %digits$ einer Umwandlungsanweisung
enthalten, kann die Feldgröße oder die Genauigkeit auch durch die
Folge *digits$ angegeben werden, wobei digits die Position einer Ganz-
zahl in der Argumentliste angibt.
Wenn numerierte Argumentangaben verwendet werden, verlangt die Angabe
des nten Arguments, daß alle vorhergehenden Argumente, vom ersten bis
zum (n-1)ten, im Format-String angegeben werden.
Alle Formen der printf()-Funktionen berücksichtigen die Eingabe eines
sprachenabhängigen Dezimalzeichens. Das Dezimalzeichen ist durch die
Umgebung des Programms (LCNUMERIC) definiert. In der C-Umgebung oder
in einer Umgebung, in der das Dezimalzeichen nicht definiert ist, ent-
spricht es standardmäßig dem Punkt.
Flags
' Der ganzzahlige Teil von dem Ergebnis einer Dezimalumwandlung (%i,
%d, %u, %f, %g oder %G) wird mit Tausendertrennzeichen ausgegeben.
Bei anderen Umwandlungen ist das Verhalten nicht definiert. Diese
Option wird ab XPG4-Modus unterstützt.
- Das Ergebnis der Umwandlung wird linksbündig im Feld ausgegeben.
(Ohne Angabe dieses Flags wird es rechtsbündig ausgegeben.)
+ Das Ergebnis einer Umwandlung mit Vorzeichen beginnt immer mit
einem Vorzeichen (+ oder -).
<blank>
Wenn das erste Zeichen einer Umwandlung mit Vorzeichen kein Vorzei-
chen ist, wird vor dem Ergebnis ein Leerzeichen eingefügt. Dies
bedeutet, daß das Leerzeichen ignoriert wird, wenn es zusammen mit
dem Zeichen + angegeben wird.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
# Der Wert soll in eine andere Form umgewandelt werden. Bei c, d, i,
s und u hat dieses Flag keine Auswirkungen. Bei o wird die Genauig-
keit erhöht, um zu erzwingen, daß die erste Ziffer des Ergebnisses
eine Null ist. Bei x (oder X) wird einem Ergebnis, das ungleich
null ist, ein 0x (oder 0X) vorangestellt. Bei e, E, f, g und G ent-
hält das Ergebnis immer einen Dezimalpunkt, selbst wenn dem Punkt
keine Ziffern mehr folgen. (Normalerweise erscheint bei dem Ergeb-
nis dieser Unmwandlungen nur dann ein Dezimalpunkt, wenn eine Zif-
fer folgt.) Bei g und G werden abschließende Nullen nicht wie sonst
üblich aus dem Ergebnis gestrichen.
0 Bei d, i, o, u, x, X, e, E, f, g und G werden führende Nullen (die
einer beliebigen Vorzeichen- oder Basisangabe folgen) verwendet, um
die Feldgröße aufzufüllen; für das Auffüllen werden keine Leerzei-
chen verwendet. Wenn die Flags 0 und - zusammen angegeben werden,
wird das Flag 0 ignoriert. Bei d, i, o, u, x und X wird das Flag 0
ignoriert, wenn eine Genauigkeitsangabe vorhanden ist. Bei anderen
Umwandlungen ist das Verhalten nicht definiert.
Jedes Umwandlungszeichen liest null oder mehr Argumente. Das Ergebnis
ist nicht definiert, wenn zu wenig Argumente für das Format vorhanden
sind. Wenn das Format ausgeschöpft ist und noch Argumente übrig sind,
werden die überzähligen Argumente einfach ignoriert.
Umwandlungszeichen
c, lc
Ein Argument des Typs int wird in unsigned char umgewandelt, und
das hieraus resultierende Zeichen wird ausgegeben.
Wenn keine Angabe l vorliegt, wird das Argument des Typs int in
den Typ unassigned char umgewandelt, und das resultierende Zei-
chen wird ausgegeben. Andernfalls wird das Argument wintt umge-
wandelt wie bei einer Umwandlungsanweisung ls ohne Genauigkeits-
angabe und mit einem Argument, das auf einen aus zwei Elementen
bestehenden Array des Typs wchart zeigt, wobei das erste Element
das Argument wintt für die Umwandlungsanweisung lc und das
zweite ein Null-Wide-Character enthält.
C Das Argument des Typs wchart wird in einen Byte-Array umgewan-
delt, der ein Zeichen darstellt, und das resultierende Zeichen
wird ausgegeben. Wenn die Genauigkeit angegeben ist, ist deren
Auswirkung nicht definiert. Die Umwandlung entspricht einer
Umwandlung durch die Funktion wctomb().
Achtung: Diese Umwandlungsanweisung wird ab XPG4-Modus unter-
stützt.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
d, i, o, u, x, X
Das Argument vom Typ int wird in eine vorzeichenbehaftete Dezi-
malzahl (d oder i), eine vorzeichenlose Oktalzahl (o), eine vor-
zeichenlose Dezimalzahl (u) oder eine vorzeichenlose Hexadezimal-
zahl (x und X) umgewandelt. Die Umwandlung x verwendet die Buch-
staben abcdef und die Umwandlung X die Buchstaben ABCDEF. Die
Genauigkeitsangabe gibt die Mindestanzahl der Ziffern an, die
ausgegeben werden sollen. Wenn der umzuwandelnde Wert auch durch
weniger Ziffern dargestellt werden kann, wird er mit führenden
Nullen erweitert. Die Voreinstellung für die Genauigkeit ist 1.
Das Ergebnis einer Umwandlung des Wertes 0 mit der Genauigkeit 0
gibt kein Zeichen.
e, E Ein Argument des Typs double wird in eine dezimale Darstellung
der Form [-]d.ddde±dd umgewandelt, wobei eine Ziffer vor dem
Dezimalpunkt steht (die ungleich null ist, falls das Argument
ungleich null ist) und die Anzahl der Ziffern nach dem Dezimal-
zeichen der Genauigkeit entspricht. Wenn die Genauigkeitsangabe
fehlt, werden 6 Stellen ausgegeben. Ist die Genauigkeit 0 und das
Flag # nicht angegeben, erscheint kein Dezimalzeichen. Das
Umwandlungszeichen E erzeugt eine Zahl mit E anstatt e am Anfang
des Exponenten. Der Exponent besteht immer aus mindestens zwei
Ziffern. Der Wert wird auf die entsprechenden Ziffernanzahl
gerundet.
f Ein Argument des Typs double wird in eine dezimale Darstellung
der Form [-]ddd.ddd umgewandelt, wobei die Anzahl der Dezimalzif-
fern hinter dem Dezimalpunkt [siehe setlocale(3C)] der Genauig-
keitsangabe entspricht. Wenn die Genauigkeitsangabe fehlt, werden
6 Stellen ausgegeben. Ist die Genauigkeit 0 und das Flag # nicht
angegeben, erscheint kein Dezimalpunkt. Wenn ein Dezimalpunkt
ausgegeben wird, geht diesem mindestens eine Ziffer voraus. Der
Wert wird auf die entsprechende Ziffernanzahl gerundet.
g, G Ein Argument des Typs double wird in der Form f oder e (bezie-
hungsweise in der Form E im Falle einer Umwandlungsanweisung G)
ausgegeben. Die Genauigkeit gibt die Anzahl der signifikanten
Stellen an. Wenn die Genauigkeit null ist, wird der Wert 1 ange-
nommen. Das verwendete Format hängt von dem umgewandelten Wert
ab: Form e (oder E) wird nur dann verwendet, wenn der aus der
Umwandlung resultierende Exponent kleiner als -4 oder größer oder
gleich der Genauigkeitsangabe ist. Abschließende Nullen werden
aus dem Bruchteil des Ergebnisses gestrichen. Ein Dezimalpunkt
erscheint nur dann, wenn ihm eine Ziffer folgt.
hd, hi, ho, hu, hx, hX
Gibt an, daß die entsprechende Umwandlungsanweisung auf ein Argu-
ment short int oder unsigned short int angewendet wird. Das Argu-
ment wird entsprechend der C-Regeln zur Wertumwandlung unter-
stützt, und sein Wert wird vor dem Drucken in ein short int oder
unsigned short int umgewandelt.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
hn Gibt an, daß die entsprechende Umwandlungsanweisung ein Zeiger
auf short int ist.
ld, li, lo, lu, lx, lX
Gibt an, daß die entsprechende Umwandlungsanweisung auf ein long
int- oder unsigned long int-Argument angewendet wird.
lld, llx
Gibt an, daß die entsprechende Umwandlungsanweisung auf ein long
long int- oder unsigned long long int-Argument angewendet wird.
ln Gibt an, daß die entsprechende Umwandlungsanweisung auf einen
Zeiger auf ein long int-Argument angewendet wird.
Le, LE, Lf, Lg, LG
Gibt an, daß die entsprechende Umwandlungsanweisung auf ein long
double-Argument angewendet wird.
Achtung: Wenn vor einer anderen als den oben aufgeführten Umwand-
lungsanweisungen ein h, l oder L steht, ist das Verhalten nicht
definiert.
n Das Argument ist ein Zeiger auf ein Objekt des Typs int sein, in
das die Anzahl der Zeichen geschrieben wird, die bisher durch
diesen Aufruf der Funktion printf(), fprintf() oder sprintf() auf
die Standardausgabe geschrieben wurden. Kein Argument wird umge-
wandelt.
p Das Argument ist ein Zeiger auf void. Der Wert des Zeigers wird
in eine implementierungsabhängige Menge von Folgen druckbarer
Zeichen umgewandelt, die der Menge der Folgen entsprechen sollte,
die durch die Formatangabe %p der Funktion scanf() erkannt wer-
den.
s, ls
Das Argument ist ein Zeiger auf char und Zeichen aus dem String
werden bis ausschließlich des abschließenden Nullzeichens
geschrieben. Wenn die Genauigkeit angegeben ist, werden nicht
mehr Zeichen als angegeben geschrieben. Wenn die Genauigkeit
nicht angegeben ist, wird sie als unendlich betrachtet, so daß
alle Zeichen bis zum ersten Nullzeichen ausgegeben werden. Ein
Wert NULL für ein Argument führt zu nicht definierten Ergebnis-
sen.
Wenn eine Angabe l vorliegt, wird das Argument als ein Zeiger auf
einen Array des Typs wchart interpretiert. Wide-Characters aus
dem Array werden in Mehrbytezeichen umgewandelt (so wie bei einem
Aufruf der Funktion wcrtomb(), wobei der Umwandlungsstatus durch
ein Objekt des Typs mbstatet beschrieben wird, das vor der
Umwandlung des ersten Wide-Characters auf Null gesetzt wird) und
zwar bis einschließlich zu einem abschließenden Null-Wide-Charac-
ter. Die resultierenden Mehrbytezeichen werden bis (aber nicht
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
einschließlich) zu einem abschließenden Nullzeichen (Byte) ausge-
geben. Wenn keine Genauigkeit angegeben ist, enthält der Array
ein Null-Wide-Character. Wenn eine Genauigkeit angegeben ist,
werden nicht mehr Zeichen (Bytes) als angegeben ausgegeben (ein-
schließlich Umwandlungsfolgen falls vorhanden) und der Array muß
ein Null-Wide-Character enthalten (um der durch die Genauigkeit
angegebenen Länge der Mehrbytezeichenfolge zu entsprechen), wenn
die Funktion auf ein Wide-Character zugreifen muß, das um ein
Zeichen über das Ende des Arrays hinausgeht. Es werden nur voll-
ständige Mehrbytezeichen geschrieben. Wenn Mehrbytezeichen eine
statusabhängige Codierung aufweisen, kann dies zu redundanten
Umwandlungsfolgen führen.
S Das Argument muß ein Zeiger auf einen Array vom Typ wchart sein.
Wide-Character-Werte aus dem Array werden bis (aber nicht ein-
schließlich) zu einem abschließenden Null-Wide-Character-Code in
eine Bytefolge umgewandelt und die sich hieraus ergebenden Bytes
werden ausgegeben. Wenn die Genauigkeit angegeben ist, werden
nicht mehr als die angegebenen Bytes und nur vollständige Zeichen
ausgegeben. Wenn die Genauigkeit nicht angegeben oder größer als
die Größe des Arrays der umgewandelten Bytes ist, muß der Array
mit den Wide-Characters mit einem Null-Wide-Character abgeschlos-
sen werden. Die Umwandlung entspricht einer Umwandlung durch die
Funktion wcstombs().
Achtung: Diese Umwandlungsanweisung wird ab XPG4-Modus unter-
stützt.
% Ausgabe eines %; kein Argument wird umgewandelt.
Wenn das Zeichen nach % oder %digits$ kein gültiges Umwandlungszeichen
ist, ist das Ergebnis der Umwandlung nicht definiert.
Wenn ein Gleitkommawert der internen Darstellung für unendlich ent-
spricht, wird [±]inf ausgegeben, wobei inf je nach Umwandlungszeichen
entweder inf oder INF ist. Bei der Ausgabe des Vorzeichens gelten die
oben beschriebenen Regeln.
Wenn ein Gleitkommawert der internen Darstellung für NaN entspricht,
wird [±]nan0xm ausgegeben. Abhängig vom Umwandlungszeichen ist nan
entweder nan oder NAN. Zusätzlich stellt 0xm den signifikantesten Teil
der Mantisse dar. Abhängig vom Umwandlungszeichen ist x entweder x
oder X, und m verwendet die Buchstaben abcdef oder ABCDEF. Bei der
Ausgabe des Vorzeichens gelten die oben beschriebenen Regeln.
In keinem Fall bewirkt eine nicht angegebene oder eine kleine Feld-
größe, daß ein Feld abgeschnitten wird. Wenn das Ergebnis einer
Umwandlung größer als die Feldgröße ist, wird das Feld einfach erwei-
tert, um das Ergebnis aufnehmen zu können. Durch printf() und
fprintf() generierte Zeichen werden so ausgegeben, als ob die Routine
putc() aufgerufen worden wäre.
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
BEISPIELE
Die Ausgabe von Datum und die Uhrzeit in der Form Sunday, July 3,
10:02, wobei weekday und month Zeiger auf Strings mit Endenull sind,
erzielen Sie folgendermaßen:
printf("%s, %s %i, %d:%.2d",
weekday, month, day, hour, min);
Die folgende Routine bewirkt die Ausgabe von "pi" mit einer Genauig-
keit von 5 Dezimalstellen:
printf("pi = %.5f", 4 * atan(1.0));
RÜCKGABEWERTE
printf(), fprintf() und sprintf() geben die Anzahl der übertragenen
Zeichen oder, wenn ein Fehler aufgetreten ist, einen negativen Wert
zurück.
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
Die Funktion schlägt fehl, wenn entweder der Datenstrom nicht gepuf-
fert ist oder der Puffer des Datenstroms geleert werden mußte; ferner
wenn:
EAGAIN Das Flag ONONBLOCK für den Dateideskriptor, der stream
zugrundeliegt, ist gesetzt, und der Prozeß wurde beim
Schreibvorgang verzögert.
EBADF Der Dateideskriptor, der stream zugrundeliegt, ist kein gül-
tiger Dateideskriptor, der zum Schreiben geöffnet ist.
EFBIG Es wurde versucht, in eine Datei zu schreiben, deren Größe
die maximale Dateigröße oder die maximale Dateigröße des
Prozesses überschreitet.
EFBIG Die Datei ist eine reguläre Datei, und es wurde versucht,
bis hin oder über den maximalen Offset hinaus zu schreiben,
der dem entsprechenden Datenstrom zugeordnet ist.
EINTR Infolge eines Signals wurde die Schreiboperation beendet,
und es wurden keine Daten übertragen.
EIO Ein physischer Ein-/Ausgabefehler ist aufgetreten, oder der
Prozeß gehört zu einer Hintergrundprozeßgruppe, welche auf
das kontrollierende Terminal zu schreiben versucht. TOSTOP
ist gesetzt, weder ignoriert noch blockiert der Prozeß
SIGTTOU, und die Prozeßgruppe des Prozesses ist verwaist.
Dieser Fehler kann auch unter implementationsabhängigen
Bedingungen gemeldet werden.
Seite 8 Reliant UNIX 5.44 Gedruckt 11/98
printf(3S) printf(3S)
ENOSPC Es war kein freier Platz auf dem Gerät, das die Datei ent-
hält, mehr übrig.
EPIPE Es wurde versucht, auf eine Pipe oder FIFO zu schreiben, die
für keinen Prozeß leseberechtigt ist. Es wird auch ein Sig-
nal SIGPIPE zum Prozeß gesendet.
Die Funktion kann fehlschlagen, falls:
EILSEQ Ein Wide-Character-Code, dem kein gültiges Zeichen ent-
spricht, wurde entdeckt.
EINVAL Es sind nicht genügend Argumente vorhanden.
ENOMEM Es ist nur unzureichend Speicherplatz vorhanden.
ENXIO Es wurde eine Anforderung an ein nicht-existierendes Gerät
gemacht bzw. die Anforderung ist außerhalb der Möglichkeiten
des Geräts.
HINWEISE
Die Option ' und die Umwandlungen %C und %S werden ab XPG4-Modus
unterstützt.
SIEHE AUCH
exit(2), lseek(2), write(2), abort(3C), ecvt(3C), setlocale(3C),
putc(3S), scanf(3S), stdio(3S), lfs(5), stdio(5).
Seite 9 Reliant UNIX 5.44 Gedruckt 11/98