.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
.\"
.\" 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.
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" 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, see
.\" .
.\" %%%LICENSE_END
.\"
.\" 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
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH PRINTF 3 "1. November 2020" GNU Linux\-Programmierhandbuch
.SH BEZEICHNUNG
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
vsprintf, vsnprintf \- formatierte Ausgabe
.SH ÜBERSICHT
.nf
\fB#include \fP
.PP
\fBint printf(const char *\fP\fIformat\fP\fB, …);\fP
\fBint fprintf(FILE *\fP\fIdatenstrom\fP\fB, const char *\fP\fIformat\fP\fB, …);\fP
\fBint dprintf(int \fP\fIdd\fP\fB, const char *\fP\fIformat\fP\fB, …);\fP
\fBint sprintf(char *\fP\fIzk\fP\fB, const char *\fP\fIformat\fP\fB, …);\fP
\fBint snprintf(char *\fP\fIzk\fP\fB, size_t \fP\fIgröße\fP\fB, const char *\fP\fIformat\fP\fB, …);\fP
\fB#include \fP
.PP
\fBint vprintf(const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vfprintf(FILE *\fP\fIdatenstrom\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vdprintf(int \fP\fIdd\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vsprintf(char *\fP\fIzk\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vsnprintf(char *\fP\fIzk\fP\fB, size_t \fP\fIgröße\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
.fi
.PP
.RS -4
Mit Glibc erforderliche Feature\-Test\-Makros (siehe
\fBfeature_test_macros\fP(7)):
.RE
.PP
.ad l
\fBsnprintf\fP(), \fBvsnprintf\fP():
.RS 4
_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
|| /* Glibc\-Versionen <= 2.19: */ _BSD_SOURCE
.RE
.PP
\fBdprintf\fP(), \fBvdprintf\fP():
.PD 0
.RS 4
.TP 4
Seit Glibc 2.10:
_POSIX_C_SOURCE\ >=\ 200809L
.TP
Vor Glibc 2.10:
_GNU_SOURCE
.RE
.ad
.PD
.SH BESCHREIBUNG
Die Funktionenfamilie \fBprintf\fP() erzeugt Ausgaben in einem im Folgenden
beschriebenen \fIformat\fP. Die Funktionen \fBprintf\fP() und \fBvprintf\fP()
schreiben ihre Ausgabe in den Standardausgabedatenstrom \fIstdout\fP;
\fBfprintf\fP() und \fBvfprintf\fP() schreiben in den angegebenen
Ausgabedatenstrom \fIdatenstrom\fP; \fBsprintf\fP(), \fBsnprintf\fP(), \fBvsprintf\fP()
und \fBvsnprintf\fP() schreiben in die Zeichenkette \fIzk\fP.
.PP
Die Funktion \fBdprintf\fP() ist zu der Funktion \fBfprintf\fP() identisch, außer
dass sie in einen Dateideskriptor \fIdd\fP statt in einen \fIstdio\fP\-Datenstrom
ausgibt.
.PP
Die Funktionen \fBsnprintf\fP() und \fBvsnprintf\fP() schreiben höchstens \fIgröße\fP
Bytes (einschließlich des abschließenden Nullbytes (»\e0«) nach \fIzk\fP.
.PP
Die Funktionen \fBvprintf\fP(), \fBvfprintf\fP(), \fBvdprintf\fP(), \fBvsprintf\fP(),
\fBvsnprintf\fP() sind äquivalent zu den Funktionen \fBprintf\fP(),
\fBfprintf\fP(),\fBdprintf\fP(), \fBsprintf\fP() bzw. \fBsnprintf\fP(), nur dass sie mit
einer \fIva_list\fP statt einer variablen Zahl von Argumenten aufgerufen
werden. Diese Funktionen rufen das Makro \fIva_end\fP nicht auf. Daher ist der
Wert von \fIap\fP nach dem Aufruf nicht definiert. Siehe \fBstdarg\fP(3).
.PP
Alle diese Funktionen schreiben die Ausgabe unter Kontrolle einer
\fIformat\fP\-Zeichenkette, die angibt, wie die folgenden Argumente (oder
Argumente, auf die mittels der Möglichkeit der variablen Zahl von Argumenten
von \fBstdarg\fP(3) zugegriffen wird) für die Ausgabe konvertiert werden.
.PP
C99 und POSIX.1\-2001 legen fest, dass die Ergebnisse nicht definiert sind,
wenn ein Aufruf von \fBsprintf\fP(), \fBsnprintf\fP(), \fBvsprintf\fP() oder
\fBvsnprintf\fP() zu einem Kopieren zwischen überlappenden Objekten führen
würde (z.B. wenn der Ausgabepuffer und eines der übergebenen
Eingabe\-Argumente sich auf den gleichen Puffer beziehen). Siehe ANMERKUNGEN.
.SS "Format der Formatzeichenkette"
Die Formatzeichenkette ist eine Zeichenkette, die, so vorhanden, in ihrem
initialen Shift\-Zustand beginnt und endet. Die Formatzeichenkette setzt sich
zusammen aus Null oder mehr Anweisungen: normale Zeichen (nicht \fB%\fP) werden
unverändert in den Ausgabedatenstrom kopiert; Umwandlungsanweisungen fordern
jeweils null oder mehr Argumente. Jede Umwandlungsanweisung wird durch das
Zeichen \fB%\fP eingeleitet und endet mit einem
\fIUmwandlungskennzeichner\fP. Dazwischen können (in dieser Reihenfolge) null
oder mehr \fIFlags\fP (Schalter), eine optionale minimale \fIFeldbreite\fP, eine
optionale \fIGenauigkeit\fP und ein optionaler \fILängenmodifikator\fP vorkommen.
.PP
Die Argumente müssen (nach \fITypumwandlung\fP) genau zu den
Umwandlungskennzeichner passen. Standardmäßig werden die Argumente in der
angegebenen Reihenfolge benutzt, wobei jeder »*« (siehe \fIFeldbreite\fP und
\fIGenauigkeit\fP weiter unten) und jedes Umwandlungsbezeichner das nächste
Argument abfragt (und es ist ein Fehler, wenn nicht ausreichend Argumente
angegeben sind). Es kann auch an jeder Stelle, die ein Argument erfordert,
explizit angeben werden, welches Argument verwendet wird, indem »%m$«
anstelle von »%« und »*m$« anstelle von »*« geschrieben wird, wobei die
Dezimalzahl \fIm\fP die Position des gewünschten Arguments in der Argumentliste
angibt, beginnend mit 1. Damit sind
.PP
.in +4n
.EX
printf("%*d", width, num);
.EE
.in
.PP
und
.PP
.in +4n
.EX
printf("%2$*1$d", width, num);
.EE
.in
.PP
gleichwertig. Die zweite Form ermöglicht wiederholte Referenzen auf das
gleiche Argument. Der C99\-Standard schließt die aus der \fISingle Unix
Specification\fP stammende Form mit \(aq$\(aq nicht mit ein. Wenn die
\(aq$\(aq verwendende Form eingesetzt wird, muss sie durchgehend für alle
Umwandlungen, die ein Argument erfordern, und alle Breiten\- und
Genauigkeitsargumente verwendet werden, darf aber mit »%%«\-Formaten (die
kein Argument erfordern) vermischt werden. Es darf keine Lücken in der Zahl
der mittels \(aq$\(aq spezifizierten Argumente geben; beispielsweise muss,
wenn die Argumente 1 und 3 angegeben werden, auch Argument 2 irgendwo in der
Formatzeichenkette erwähnt werden.
.PP
Für einige numerische Umwandlungen wird ein Radixzeichen (»Dezimalpunkt«)
oder ein Tausender\-Gruppierungszeichen verwendet. Das tatsächlich benutzte
Zeichen hängt von der LC_NUMERIC\-Komponente der Locale ab (siehe
\fBsetlocale\fP(3)). Die POSIX\-Locale benutzt \(aq.\(aq als Radixzeichen und
hat kein Gruppierungszeichen. Damit resultiert
.PP
.in +4n
.EX
printf("%\(aq.2f", 1234567.89);
.EE
.in
.PP
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 "Zeichen für die Schalter (Flags)"
Dem Zeichen % folgen null oder mehr der folgenden Schalter:
.TP
\fB#\fP
Der Wert soll in eine »alternative Form« gewandelt werden. Bei
\fBo\fP\-Umwandlungen ist das erste Zeichen der Ausgabe eine Null (indem eine
»0« vorangestellt wird, wenn der Wert nicht schon Null war). Bei den
Umwandlungen \fBx\fP und \fBX\fP wird einem Ergebnis ungleich Null die
Zeichenkette »0x« (oder »0X« bei \fBX\fP) vorangestellt. Bei den Umwandlungen
\fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP und \fBG\fP enthält das Ergebnis immer
ein Dezimaltrennzeichen, auch wenn ihm keine Ziffern folgen. (Normalerweise
tritt ein Dezimaltrennzeichen nur in Ergebnissen auf, wenn ihm eine Ziffer
folgt.) Bei den Umwandlungen \fBg\fP und \fBG\fP werden nachfolgende Nullen nicht
aus dem Ergebnis entfernt, wie sie es normalerweise würden. Für andere
Umwandlungen ist das Ergebnis nicht definiert.
.TP
\fB\&0\fP
Der Wert soll mit Nullen aufgefüllt werden. Bei den Umwandlungen \fBd\fP, \fBi\fP,
\fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP und \fBG\fP
wird der umgewandelte Wert links mit Nullen anstatt mit Leerzeichen
aufgefüllt. Werden sowohl \fB\&0\fP als auch \fB\-\fP angegeben, so wird \fB\&0\fP
ignoriert. Wenn eine Genauigkeit bei einer numerischen Umwandlung (\fBd\fP,
\fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP und \fBX\fP) angegeben ist, wird der Schalter \fB\&0\fP
ignoriert. Für andere Umwandlungen ist das Ergebnis nicht definiert.
.TP
\fB\-\fP
Der umgewandelte Wert soll linksbündig an der Feldgrenze ausgerichtet werden
(Standard ist rechtsbündige Ausrichtung). Außer bei der Umwandlung \fBn\fP wird
der umgewandelte Wert rechts mit Leerzeichen aufgefüllt statt links mit
Leerzeichen oder Nullen. Ein \fB\-\fP setzt ein \fB\&0\fP außer Kraft, falls beide
angegeben sind.
.TP
\fB\(aq \(aq\fP
(ein Leerzeichen) Vor einer positiven Zahl (oder einer leeren Zeichenkette),
die durch eine vorzeichenbehaftete Umwandlung mit erzeugt wurde, soll ein
Leerzeichen erhalten bleiben.
.TP
\fB+\fP
Vor jeder durch eine vorzeichenbehaftete Umwandlung erzeugten Zahl soll ein
Vorzeichen (+ oder \-) platziert werden. Standardmäßig wird ein Vorzeichen
nur für negative Zahlen verwendet. Ein \fB+\fP übersteuert ein Leerzeichen,
falls beide verwendet werden.
.PP
Die obigen fünf Schalter werden vom C99\-Standard definiert. Die Single UNIX
Specification spezifiziert einen weiteren Schalter.
.TP
\fB\(aq\fP
gibt für dezimale Umwandlungen (\fBi\fP, \fBd\fP, \fBu\fP, \fBf\fP, \fBF\fP, \fBg\fP, \fBG\fP)
an, dass die Ausgabe mit dem Tausender\-Gruppierungszeichen gruppiert werden
soll, wenn die Locale\-Information eines angibt (siehe
\fBsetlocale\fP(3)). Beachten Sie, dass viele Versionen von \fBgcc\fP(1) diese
Option nicht auswerten können und eine Warnung ausgeben werden. SUSv2
schließt \fI%\(aqF\fP nicht mit ein, aber SUSv3 fügt es hinzu.
.PP
Glibc 2.2 fügt ein weiteres Schalterzeichen hinzu.
.TP
\fBI\fP
.\" outdigits keyword in locale file
Für dezimale Ganzzahlumwandlungen (\fBi\fP, \fBd\fP, \fBu\fP) benutzt die Ausgabe die
alternativen Ausgabeziffern der Locale, wenn es solche gibt. Beispielsweise
bewirkt diese Option seit Glibc 2.2.3 arabisch\-indische Ziffern in der
persischen (»fa_IR«) Locale.
.SS Feldbreite
Diese optionale Dezimalzahl gibt die minimale Feldbreite an; die erste
Ziffer ist von Null verschieden. Wenn der umgewandelte Wert weniger Zeichen
als die Feldbreite hat, wird er links mit Leerzeichen aufgefüllt (oder
rechts, wenn der Schalter für Linksbündigkeit gesetzt ist). Statt einer
Dezimalzahl kann auch »*« oder »*m$« (für irgendeine Ganzzahl \fIm\fP)
angegeben werden, um zu spezifizieren, dass die Feldbreite im nächsten (oder
\fIm\fP\-ten) Argument gegeben ist, welches vom Type \fIint\fP sein muss. Eine
negative Feldbreite wird als Schalter \(aq\-\(aq gefolgt von einer positiven
Breite interpretiert. In keinem Fall bewirkt eine fehlende oder kleine
Feldbreite das Abschneiden eines Feldes; ist das Ergebnis einer Umwandlung
breiter als die Feldbreite, so wird das Feld erweitert, um das Ergebnis
aufzunehmen.
.SS Genauigkeit
Eine optionale Genauigkeit in der Form eines Punkts (\(aq.\(aq) gefolgt von
einer optionalen Dezimalzahl. Statt einer Dezimalzahl kann auch mittels »*«
oder »*m$« (für irgendeine Dezimalzahl \fIm\fP) angegeben werden, dass die
Genauigkeit im nächsten (oder \fIm\fP\-ten) Argument gegeben ist, welches den
Typ \fIint\fP haben muss. Falls die Genauigkeit einfach als \(aq.\(aq angegeben
ist, wird eine dafür der Wert Null angenommen. Eine negative Genauigkeit
wird angenommen, falls die Genauigkeitsangabe weggelassen wird. Dies gibt
die minimale Anzahl der Ziffern an, die bei den Umwandlungen \fBd\fP, \fBi\fP,
\fBo\fP, \fBu\fP, \fBx\fP und \fBX\fP erscheinen, bzw. die Anzahl der Ziffern nach dem
Dezimaltrennzeichen bei \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP und \fBF\fP, die maximale
Anzahl von signifikanten Ziffern bei \fBg\fP und \fBG\fP oder die maximale Anzahl
von auszugebenden Zeichen einer Zeichenkette bei \fBs\fP und \fBS\fP.
.SS Längenmodifikator
Im Folgenden steht »Ganzzahlumwandlung« für \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP
oder \fBX\fP.
.TP
\fBhh\fP
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ \fIsigned
char\fP oder \fIunsigned char\fP oder eine folgende \fBn\fP\-Umwandlung entspricht
einem Zeiger auf ein \fIsigned char\fP\-Argument.
.TP
\fBh\fP
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ \fIshort\fP
oder \fIunsigned short\fP oder eine folgende \fBn\fP\-Umwandlung entspricht einem
Zeiger auf ein \fIshort\fP\-Argument.
.TP
\fBl\fP
(ell) Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
\fIlong\fP oder \fIunsigned long\fP oder eine folgende \fBn\fP\-Umwandlung entspricht
einem Zeiger auf ein \fIlong\fP\-Argument oder eine folgende \fBc\fP\-Umwandlung
entspricht einem \fIwint_t\fP\-Argument oder eine folgende \fBs\fP\-Umwandlung
entspricht einem Zeiger auf ein \fIwchar_t\fP\-Argument.
.TP
\fBll\fP
(ell\-ell) Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
\fIlong long\fP oder \fIunsigned long long\fP oder eine folgende \fBn\fP\-Umwandlung
entspricht einem Zeiger auf ein \fIlong long\fP\-Argument.
.TP
\fBq\fP
Ein Synonym für \fBll\fP. Dies ist eine aus BSD abgeleitete nicht
standardisierte Erweiterung, vermeiden sie die Verwendung in neuem Code.
.TP
\fBL\fP
Eine folgende \fBa\fP\-, \fBA\fP\-, \fBe\fP\-, \fBE\fP\-, \fBf\fP\-, \fBF\fP\-, \fBg\fP\- oder
\fBG\fP\-Umwandlung entspricht einem \fIlong double\fP\-Argument. C99 erlaubt %LF,
aber SUSv2 nicht.
.TP
\fBj\fP
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
\fIintmax_t\fP oder \fIuintmax_t\fP oder eine folgende \fBn\fP\-Umwandlung entspricht
einem Zeiger auf ein \fIintmax_t\fP\-Argument.
.TP
\fBz\fP
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
\fIssize_t\fP oder \fIssize_t\fP oder eine folgende \fBn\fP\-Umwandlung entspricht
einem Zeiger auf ein \fIsize_t\fP\-Argument.
.TP
\fBZ\fP
Ein nicht standardisiertes Synonym für \fBz\fP, das von vor dem Auftauchen von
\fBz\fP stammt. Verwenden Sie es nicht in neuem Code.
.TP
\fBt\fP
Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ
\fIptrdiff_t\fP oder eine folgende \fBn\fP\-Umwandlung entspricht einem Zeiger auf
ein \fIptrdiff_t\fP\-Argument.
.PP
SUSv3 spezifiziert alle oben genannten, außer den Modifikatoren, die
explizit als nicht standardisierte Erweiterungen vermerkt sind. SUSv2 kennt
nur die Längenmodifikatoren \fBh\fP (in \fBhd\fP, \fBhi\fP, \fBho\fP, \fBhx\fP, \fBhX\fP,
\fBhn\fP) und \fBl\fP (in \fBld\fP, \fBli\fP, \fBlo\fP, \fBlx\fP, \fBlX\fP, \fBln\fP, \fBlc\fP, \fBls\fP)
und \fBL\fP (in \fBLe\fP, \fBLE\fP, \fBLf\fP, \fBLg\fP, \fBLG\fP).
.PP
.\"
Als eine nicht standardisierte Erweiterung behandelt die GNU\-Implementierung
\fBll\fP und \fBL\fP als Synonyme, so dass Sie \fBllg\fP (als Synonym für das
standardmäßige \fBLg\fP) und \fBLd\fP (als Synonym für das standardmäßige \fBlld\fP)
schreiben können. Dies ist nicht portabel.
.SS Umwandlungskennzeichner
Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt. Die
Umwandlungskennzeichner und ihre Bedeutung sind:
.TP
\fBd\fP, \fBi\fP
Das \fIint\fP\-Argument wird umgewandelt in eine vorzeichenbehaftete
Dezimalzahl. Die Genauigkeit, sofern vorhanden, gibt die minimale Anzahl von
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 ausgegeben, so
ist die Ausgabe leer.
.TP
\fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP
Das \fIunsigned int\fP\-Argument wird in eine vorzeichenlose Oktal\- (\fBo\fP),
Dezimal\- (\fBu\fP) oder Hexadezimalzahl (\fBx\fP und \fBX\fP) umgewandelt. Die
Buchstaben \fBabcdef\fP werden für \fBx\fP\-Umwandlungen benutzt; die Buchstaben
\fBABCDEF\fP für \fBX\fP\-Umwandlungen. 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
ausgegeben, so ist die Ausgabe leer.
.TP
\fBe\fP, \fBE\fP
Das \fIdouble\fP\-Argument wird gerundet und in die Form [\-]d\fB\&.\fPddd\fBe\fP\+\-dd
umgewandelt, wobei eine Ziffer (die sich von 0 unterscheidet, falls das
Argument nicht 0 ist) vor dem Dezimaltrennzeichen erscheint und die Anzahl
der Ziffern dahinter der Genauigkeit entspricht; falls die Genauigkeit
fehlt, wird sie als 6 angenommen; falls die Genauigkeit Null ist, erscheint
kein Dezimaltrennzeichen. Eine \fBE\fP\-Umwandlung verwendet den Buchstaben \fBE\fP
(in Gegensatz zu \fBe\fP), um den Exponenten einzuleiten. Der Exponent enthält
immer mindestens zwei Ziffern; falls der Wert Null ist, ist der Exponent 00.
.TP
\fBf\fP, \fBF\fP
Das \fIdouble\fP\-Argument wird gerundet und umgewandelt in dezimale Notation im
Format [\-]ddd\fB\&.\fPddd, wobei die Anzahl der Ziffern hinter dem
Dezimaltrennzeichen der vorgegebenen Genauigkeit entspricht. Falls die
Genauigkeit fehlt, wird sie als 6 angenommen; falls die Genauigkeit Null
ist, erscheint kein Dezimaltrennzeichen. Falls ein Dezimaltrennzeichen
erscheint, befindet sich mindestens eine Ziffer davor.
.IP
(SUSv2 kennt \fBF\fP nicht und besagt, dass Zeichenketten\-Darstellungen für
Unendlich und NaN (Not a Number \- keine Zahl) verfügbar gemacht werden
können. SUSv3 fügt eine Spezifikation für \fBF\fP hinzu. Der C99\-Standard
spezifiziert »[\-]inf« oder »[\-]infinity« für Unendlich sowie eine
Zeichenkette beginnend mit »nan« für NaN im Falle von \fBf\fP und entsprechen
»[\-]INF« oder »[\-]INFINITY« oder »NAN« im Falle von \fBF\fP.)
.TP
\fBg\fP, \fBG\fP
Das \fIdouble\fP\-Argument wird in das Format \fBf\fP oder \fBe\fP (oder \fBF\fP oder
\fBE\fP für die \fBG\fP\-Umwandlung) umgewandelt. Die Genauigkeit gibt die Anzahl
der signifikanten Stellen an. Falls die Genauigkeit fehlt, werden 6 Ziffern
zurückgegeben; falls die Genauigkeit Null ist, wird sie als 1
angenommen. Form \fBe\fP wird benutzt, falls der Exponent kleiner als \-4 oder
größer oder gleich der Genauigkeit ist. Abschließende Nullen in den
Nachkommastellen werden entfernt; ein Dezimaltrennzeichen erscheint nur,
wenn ihm mindestens eine Ziffer folgt.
.TP
\fBa\fP, \fBA\fP
(C99; nicht in SUSv2, aber in SUSv3 hinzugefügt) Für die \fBa\fP\-Umwandlung
wird das \fIdouble\fP\-Argument (unter Verwendung der Buchstaben abcdef) in
hexadezimale Notation der Form [\-]\fB0x\fPh\fB\&.\fPhhhh\fBp\fP\(+-d gebracht; für
\fBA\fP werden dagegen das Präfix \fB0X\fP, die Buchstaben ABCDEF und das
Exponententrennzeichen \fBP\fP verwendet. Vor dem Dezimaltrennzeichen steht
eine hexadezimale Ziffer, die Anzahl der Stellen dahinter entspricht der
Genauigkeit. Die standardmäßige Genauigkeit genügt für eine exakte
Darstellung des Wertes, wenn eine exakte Darstellung zur Basis 2 existiert
und ist ansonsten groß genug, um Werte vom Typ \fIdouble\fP zu
unterscheiden. Die Ziffer vor dem Dezimaltrennzeichen ist für nicht
normalisierte Zahlen nicht spezifiziert und für normalisierte Zahlen nicht
Null, aber ansonsten nicht spezifiziert. Der Exponent enthält stets
mindestens eine Ziffer; falls der Wert 0 ist, ist der Exponent 0.
.TP
\fBc\fP
Wenn kein Modifikator \fBl\fP vorhanden ist, wird das \fIint\fP\-Argument
umgewandelt in einen \fIunsigned char\fP und das resultierende Zeichen
ausgegeben. Wenn ein \fBl\fP vorhanden ist, wird das \fIwint_t\fP\-Argument (wide
character) mit einem Aufruf der Funktion \fBwcrtomb\fP(3) zu einer
Multibyte\-Folge umgewandelt, mit der Konvertierung beginnend im initialen
Zustand, und die resultierende Multibyte\-Zeichenkette wird ausgegeben.
.TP
\fBs\fP
Wenn kein Modifikator \fBl\fP vorhanden ist, wird das \fIconst char\ *\fP\-Argument
erwartet als ein Zeiger auf ein Feld vom Typ Zeichen (Zeiger auf eine
Zeichenkette). Zeichen aus diesem Feld werden bis zu (aber nicht
einschließlich) des abschließenden Nullbytes (»\e0«) ausgegeben; wenn eine
Genauigkeit angegeben ist, werden nicht mehr Zeichen als die angegebene
Anzahl ausgegeben. Wenn eine Genauigkeit angegeben ist, braucht kein
Nullbyte vorhanden zu sein; wenn die Genauigkeit nicht angegeben ist oder
größer als das Feld ist, muss das Feld ein abschließendes Nullbyte
enthalten.
.IP
Wenn ein \fBl\fP vorhanden ist, wird das \fIconst wchar_t\ *\fP\-Argument als ein
Zeiger auf ein Feld von »wide characters« erwartet. Wide characters aus dem
Feld werden zu Multibyte\-Zeichen umgewandelt (jedes mit einem Aufruf der
Funktion \fBwcrtomb\fP(3), beginnend im initialen Zustand vor dem ersten weiten
Zeichen), bis zu und einschließlich des abschließenden weiten Nullbytes. Die
resultierenden Multibyte\-Zeichen werden bis zum (aber nicht einschließlich)
des abschließenden Nullbytes geschrieben. Falls eine Genauigkeit angegeben
ist, werden nicht mehr Bytes als die angegebene Anzahl ausgegeben, aber es
werden keine partiellen Multibyte\-Zeichen ausgegeben. Beachten Sie, dass die
Genauigkeit die Anzahl der geschriebenen \fIBytes\fP angibt, nicht die Anzahl
der \fIweiten Zeichen\fP oder \fIBildschirmpositionen\fP. Das Feld muss ein
abschließendes weites Nullzeichen enthalten, wenn nicht eine Genauigkeit
gegeben ist, die so klein ist, dass die Zahl der geschriebenen Bytes sie
übersteigt, bevor das Ende des Feldes erreicht ist.
.TP
\fBC\fP
(Nicht in C99, aber in SUSv2, SUSv3 und SUSv4.) Synonym für \fBlc\fP. Nicht
verwenden.
.TP
\fBS\fP
(Nicht in C99, aber in SUSv2, SUSv3 und SUSv4.) Synonym für \fBls\fP. Nicht
verwenden.
.TP
\fBp\fP
Das \fIvoid\ *\fP\-Zeiger\-Argument wird hexadezimal ausgegeben (wie bei \fB%#x\fP
oder \fB%#lx\fP).
.TP
\fBn\fP
Die Anzahl der bis dahin geschriebenen Zeichen wird in der Ganzzahl
gespeichert, die auf das korrespondierende Argument zeigt. Das Argument muss
ein \fIint\ *\fP oder eine Variante sein, deren Größe dem (optional)
angegebenen Längenmodifikator der Ganzzahl entspricht. Es wird kein Argument
umgewandelt. (Dieser Kennzeichner wird nicht von der Bionic\-C\-Bibliothek
unterstützt.) Das Verhalten ist nicht definiert, wenn die
Umwandlungsspezifikation Schalter, eine Feldbreite oder eine
Genauigkeitsangabe enthält.
.TP
\fBm\fP
(Glibc\-Erweiterung, von uClibc und Musl unterstützt) Gibt die Ausgabe von
\fIstrerror(errno)\fP aus; es ist kein Argument erforderlich.
.TP
\fB%\fP
Es wird ein \(aq%\(aq ausgegeben. Es wird kein Argument umgewandelt. Die
vollständige Umwandlungsanweisung ist \(aq%%\(aq.
.SH RÜCKGABEWERT
Nach erfolgreicher Ausführung geben diese Funktionen die Anzahl der
ausgegebenen Zeichen zurück (ohne das für den Abschluß der
Zeichenkettenausgabe verwendete Nullbyte).
.PP
Die Funktionen \fBsnprintf\fP() und \fBvsnprintf\fP() schreiben nicht mehr als
\fIgröße\fP Byte (einschließlich des abschließenden Nullbytes »\e0«))). Falls
die Ausgabe wegen dieser Begrenzung gekürzt wurde, ist der Rückgabewert die
Anzahl der Zeichen (ohne abschließendes Nullbyte), die bei ausreichendem
Speicherplatz in die Ausgabe geschrieben worden wären. Damit bedeutet ein
Rückgabewert von \fIgröße\fP oder mehr, dass die Ausgabe gekürzt wurde. (Siehe
auch im Folgenden unter ANMERKUNGEN.)
.PP
Wenn bei der Ausgabe ein Fehler auftritt, wird ein negativer Wert
zurückgegeben.
.SH ATTRIBUTE
Siehe \fBattributes\fP(7) für eine Erläuterung der in diesem Abschnitt
verwandten Ausdrücke.
.TS
allbox;
lbw23 lb lb
l l l.
Schnittstelle Attribut Wert
T{
\fBprintf\fP(),
\fBfprintf\fP(),
.br
\fBsprintf\fP(),
\fBsnprintf\fP(),
.br
\fBvprintf\fP(),
\fBvfprintf\fP(),
.br
\fBvsprintf\fP(),
\fBvsnprintf\fP()
T} Multithread\-Fähigkeit MT\-Safe locale
.TE
.sp 1
.SH "KONFORM ZU"
\fBfprintf\fP(), \fBprintf\fP(), \fBsprintf\fP(), \fBvprintf\fP(), \fBvfprintf\fP(),
\fBvsprintf\fP(): POSIX.1\-2001, POSIX.1\-2008, C89, C99.
.PP
\fBsnprintf\fP(), \fBvsnprintf\fP(): POSIX.1\-2001, POSIX.1\-2008, C99.
.PP
Die Funktionen \fBdprintf\fP() und \fBvdprintf\fP() waren ursprünglich
GNU\-Erweiterungen, die später in POSIX.1\-2008 standardisiert wurden.
.PP
.\" .PP
.\" Linux libc4 knows about the five C standard flags.
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
.\" and the conversions
.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
.\" where \fBF\fP is a synonym for \fBf\fP.
.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
.\" (This is bad, and caused serious bugs later, when
.\" support for \fB%D\fP disappeared.)
.\" No locale-dependent radix character,
.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
.\" .PP
.\" Linux libc5 knows about the five C standard flags and the \(aq flag,
.\" locale, "%m$" and "*m$".
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
.\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug).
.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
.\" but adds the conversion character
.\" .BR m ,
.\" which outputs
.\" .IR strerror(errno) .
.\" .PP
.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
Hinsichtlich des Rückgabewerts von \fBsnprintf\fP() widersprechen sich SUSv2
und der C99\-Standard: wird \fBsnprintf\fP() mit \fIgröße\fP=0 aufgerufen, dann
fordert SUSv2 einen nicht spezifizierten Rückgabewert kleiner als 1, während
C99 es zulässt, dass \fIzk\fP in diesem Fall NULL ist, und (wie immer) den
Rückgabewert als die Anzahl der Zeichen angibt, die bei ausreichend großer
Ausgabe\-Zeichenkette geschrieben worden wären. POSIX.1\-2001 und neuer
richten ihre Spezifikation von \fBsnprintf\fP() an C99 aus.
.PP
Glibc 2.1 fügt die Längenmodifikatoren \fBhh\fP, \fBj\fP, \fBt\fP und \fBz\fP sowie die
Umwandlungszeichen \fBa\fP und \fBA\fP hinzu.
.PP
Glibc 2.2 fügt das Umwandlungszeichen \fBF\fP mit C99\-Semantik sowie den
Schalter \fBl\fP hinzu.
.SH ANMERKUNGEN
Einige Programme verlassen sich leichtsinnig auf Code wie den folgenden
.PP
sprintf(buf, "%s etwas mehr Text", buf);
.PP
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
um Text an \fIbuf\fP anzuhängen. Jedoch weisen die Standards explizit darauf
hin, dass die Ergebnisse undefiniert sind, wenn Quell\- und Ziel\-Puffer beim
Aufruf von \fBsprintf\fP(), \fBsnprintf\fP(), \fBvsprintf\fP() und \fBvsnprintf\fP()
überlappen. Abhängig von der verwendeten \fBgcc\fP(1)\-Version und den gewählten
Compiler\-Optionen erzeugen Aufrufe wie das obige Beispiel \fBnicht\fP die
erwarteten Ergebnisse.
.PP
.\" .SH HISTORY
.\" UNIX V7 defines the three routines
.\" .BR printf (),
.\" .BR fprintf (),
.\" .BR sprintf (),
.\" and has the flag \-, the width or precision *, the length modifier l,
.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
.\" #, + and and no longer mentions D,O,U,X.
.\" 2.11BSD has
.\" .BR vprintf (),
.\" .BR vfprintf (),
.\" .BR vsprintf (),
.\" and warns not to use D,O,U,X.
.\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
.\" and the conversions n, p, E, G, X (with current meaning)
.\" and deprecates D,O,U.
.\" 4.4BSD introduces the functions
.\" .BR snprintf ()
.\" and
.\" .BR vsnprintf (),
.\" and the length modifier q.
.\" FreeBSD also has functions
.\" .BR asprintf ()
.\" and
.\" .BR vasprintf (),
.\" that allocate a buffer large enough for
.\" .BR sprintf ().
.\" In glibc there are functions
.\" .BR dprintf ()
.\" and
.\" .BR vdprintf ()
.\" that print to a file descriptor instead of a stream.
Seit der Glibc\-Version 2.1 ist die Implementierung der Funktionen
\fBsnprintf\fP() und \fBvsnprintf\fP() konform zu C99, verhält sich also wie oben
beschrieben. Bis Glibc 2.0.6 gaben sie im Fall gekürzter Ausgaben \-1 zurück.
.SH FEHLER
.\" .PP
.\" Linux libc4.[45] does not have a
.\" .BR snprintf (),
.\" but provides a libbsd that contains an
.\" .BR snprintf ()
.\" equivalent to
.\" .BR sprintf (),
.\" that is, one that ignores the
.\" .I size
.\" argument.
.\" Thus, the use of
.\" .BR snprintf ()
.\" with early libc4 leads to serious security problems.
Da \fBsprintf\fP() und \fBvsprintf\fP() eine beliebig lange Zeichenkette annehmen,
müssen Aufrufende darauf achten, nicht den tatsächlich verfügbaren Platz zu
überschreiten; dies ist oft unmöglich sicherzustellen. Beachten Sie, dass
die Länge der Zeichenketten oft abhängig von der Locale und schwierig
vorherzusagen sind. Benutzen Sie stattdessen \fBsnprintf\fP() und
\fBvsnprintf\fP() (oder \fBasprintf\fP(3) und \fBvasprintf\fP(3)).
.PP
.\" .PP
.\" Some floating-point conversions under early libc4
.\" caused memory leaks.
Code wie beispielsweise \fBprintf(\fP\fIfoo\fP\fB);\fP weist häufig auf einen Fehler
hin, da \fIfoo\fP das Zeichen »%« enthalten kann. Stammt \fIfoo\fP von ungeprüfter
Nutzereingabe, kann es »%n« enthalten und veranlasst \fBprintf\fP(), in den
Speicher zu schreiben und erzeugt damit ein Sicherheitsloch.
.SH BEISPIELE
Um \fIPi\fP mit fünf Dezimalstellen auszugeben:
.PP
.in +4n
.EX
#include
#include
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
.EE
.in
.PP
Um Datum und Zeit in der Form »Sunday, July 3, 10:02« auszugeben, wobei
\fIweekday\fP und \fImonth\fP Zeiger auf Zeichenketten sind:
.PP
.in +4n
.EX
#include
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
weekday, month, day, hour, min);
.EE
.in
.PP
Die meisten Länder verwenden 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:
.PP
.in +4n
.EX
#include
fprintf(stdout, format,
weekday, month, day, hour, min);
.EE
.in
.PP
wobei \fIformat\fP von der Locale abhängt und möglicherweise die Argumente
vertauscht. Mit dem Wert
.PP
.in +4n
.EX
"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
.EE
.in
.PP
könnte dann »Sonntag, 3. Juli, 10:02« dabei herauskommen.
.PP
Um eine genügend große Zeichenkette bereitzustellen und in sie zu schreiben
(der Code ist korrekt sowohl für Glibc 2.0 als auch Glibc 2.1):
.PP
.EX
#include
#include
#include
char *
make_message(const char *fmt, …)
{
int n = 0;
size_t size = 0;
char *p = NULL;
va_list ap;
/* Benötigte Größe ermitteln */
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0)
return NULL;
/* Ein zusätzliches Byte für \(aq\e0\(aq */
size = (size_t) n + 1;
p = malloc(size);
if (p == NULL)
return NULL;
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0) {
free(p);
return NULL;
}
return p;
}
.EE
.PP
Bei Kürzungen in Glibc\-Versionen vor 2.0.6 wird dies als ein Fehler
aufgefasst und nicht wohlwollend behandelt.
.SH "SIEHE AUCH"
\fBprintf\fP(1), \fBasprintf\fP(3), \fBputs\fP(3), \fBscanf\fP(3), \fBsetlocale\fP(3),
\fBstrfromd\fP(3), \fBwcrtomb\fP(3), \fBwprintf\fP(3), \fBlocale\fP(5)
.SH KOLOPHON
Diese Seite ist Teil der Veröffentlichung 5.10 des Projekts
Linux\-\fIman\-pages\fP. Eine Beschreibung des Projekts, Informationen, wie
Fehler gemeldet werden können, sowie die aktuelle Version dieser Seite
finden sich unter \%https://www.kernel.org/doc/man\-pages/.
.PP
.SH ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von
Martin Eberhard Schauer ,
Mario Blättermann
und
Helge Kreutzmann
erstellt.
.PP
Diese Übersetzung ist Freie Dokumentation; lesen Sie die
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License Version 3
.UE
oder neuer bezüglich der
Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
.PP
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden,
schicken Sie bitte eine E-Mail an die
.MT debian-l10n-german@lists.debian.org
Mailingliste der Übersetzer
.ME .