Provided by: manpages-de-dev_4.15.0-9_all 
BEZEICHNUNG
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf,
vsnprintf - formatierte Ausgabe
ÜBERSICHT
#include <stdio.h>
int printf(const char *restrict format, …);
int fprintf(FILE *restrict stream,
const char *restrict format, …);
int dprintf(int fd,
const char *restrict format, …);
int sprintf(char *restrict str,
const char *restrict format, …);
int snprintf(char *restrict str, size_t size,
const char *restrict format, …);
#include <stdarg.h>
int vprintf(const char *restrict format, va_list ap);
int vfprintf(FILE *restrict stream,
const char *restrict format, va_list ap);
int vdprintf(int fd,
const char *restrict format, va_list ap);
int vsprintf(char *restrict str,
const char *restrict format, va_list ap);
int vsnprintf(char *restrict str, size_t size,
const char *restrict format, va_list ap);
Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):
snprintf(), vsnprintf():
_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
|| /* Glibc <= 2.19: */ _BSD_SOURCE
dprintf(), vdprintf():
Seit Glibc 2.10:
_POSIX_C_SOURCE >= 200809L
Vor Glibc 2.10:
_GNU_SOURCE
BESCHREIBUNG
Die Funktionenfamilie printf() erzeugt Ausgaben in einem im Folgenden beschriebenen
format. Die Funktionen printf() und vprintf() schreiben ihre Ausgabe in den
Standardausgabedatenstrom stdout; fprintf() und vfprintf() schreiben in den angegebenen
Ausgabedatenstrom stream; sprintf(), snprintf(), vsprintf() und vsnprintf() schreiben in
die Zeichenkette str.
Die Funktion dprintf() ist zu der Funktion fprintf() identisch, außer dass sie in einen
Dateideskriptor fd statt in einen stdio(3)-Stream ausgibt.
Die Funktionen snprintf() und vsnprintf() schreiben höchstens size Bytes (einschließlich
des abschließenden NULL-Bytes ('\0')) nach str.
Die Funktionen vprintf(), vfprintf(), vdprintf(), vsprintf(), vsnprintf() sind äquivalent
zu den Funktionen printf(), fprintf(),dprintf(), sprintf() bzw. snprintf(), nur dass sie
mit einer va_list statt einer variablen Zahl von Argumenten aufgerufen werden. Diese
Funktionen rufen das Makro va_end nicht auf. Daher ist der Wert von ap nach dem Aufruf
nicht definiert. Siehe stdarg(3).
Alle diese Funktionen schreiben die Ausgabe unter Kontrolle einer format-Zeichenkette, die
angibt, wie die folgenden Argumente (oder Argumente, auf die mittels der Möglichkeit der
variablen Zahl von Argumenten von stdarg(3) zugegriffen wird) für die Ausgabe konvertiert
werden.
C99 und POSIX.1-2001 legen fest, dass die Ergebnisse nicht definiert sind, wenn ein Aufruf
von sprintf(), snprintf(), vsprintf() oder vsnprintf() 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.
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 %) werden unverändert in den Ausgabedatenstrom
kopiert; Umwandlungsanweisungen fordern jeweils null oder mehr Argumente. Jede
Umwandlungsanweisung wird durch das Zeichen % eingeleitet und endet mit einem
Umwandlungskennzeichner. Dazwischen können (in dieser Reihenfolge) null oder mehr Flags
(Schalter), eine optionale minimale Feldbreite, eine optionale Genauigkeit und ein
optionaler Längenmodifikator vorkommen.
Pauschal ist die Konvertierungssyntax wie folgt:
%[$][Schalter][Breite][.Genauigkeit][Längenmodifikator]Konvertierung
Die Argumente müssen (nach Typumwandlung) genau zu den Umwandlungskennzeichner passen.
Standardmäßig werden die Argumente in der angegebenen Reihenfolge benutzt, wobei jeder »*«
(siehe Feldbreite und Genauigkeit 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 m die Position des gewünschten
Arguments in der Argumentliste angibt, beginnend mit 1. Damit sind
printf("%*d", width, num);
und
printf("%2$*1$d", width, num);
gleichwertig. Die zweite Form ermöglicht wiederholte Referenzen auf das gleiche Argument.
Der C99-Standard schließt die aus der Single Unix Specification stammende Form mit '$'
nicht mit ein. Wenn die '$' 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 '$' spezifizierten Argumente geben;
beispielsweise muss, wenn die Argumente 1 und 3 angegeben werden, auch Argument 2 irgendwo
in der Formatzeichenkette erwähnt werden.
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 setlocale(3)). Die POSIX-Locale benutzt '.' als
Radixzeichen und hat kein Gruppierungszeichen. Damit resultiert
printf("%'.2f", 1234567.89);
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.
Zeichen für die Schalter (Flags)
Dem Zeichen % folgen null oder mehr der folgenden Schalter:
# Der Wert soll in eine »alternative Form« gewandelt werden. Bei o-Umwandlungen ist
das erste Zeichen der Ausgabe eine Null (indem eine »0« vorangestellt wird, wenn
der Wert nicht schon Null war). Bei den Umwandlungen x und X wird einem Ergebnis
ungleich Null die Zeichenkette »0x« (oder »0X« bei X) vorangestellt. Bei den
Umwandlungen a, A, e, E, f, F, g und G 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 g und G werden nachfolgende Nullen nicht aus dem Ergebnis entfernt,
wie sie es normalerweise würden. Für andere Umwandlungen ist das Ergebnis nicht
definiert.
0 Der Wert soll mit Nullen aufgefüllt werden. Bei den Umwandlungen d, i, o, u, x, X,
a, A, e, E, f, F, g und G wird der umgewandelte Wert links mit Nullen anstatt mit
Leerzeichen aufgefüllt. Werden sowohl 0 als auch - angegeben, so wird 0 ignoriert.
Wenn eine Genauigkeit bei einer numerischen Umwandlung (d, i, o, u, x und X)
angegeben ist, wird der Schalter 0 ignoriert. Für andere Umwandlungen ist das
Ergebnis nicht definiert.
- Der umgewandelte Wert soll linksbündig an der Feldgrenze ausgerichtet werden
(Standard ist rechtsbündige Ausrichtung). Außer bei der Umwandlung n wird der
umgewandelte Wert rechts mit Leerzeichen aufgefüllt statt links mit Leerzeichen
oder Nullen. Ein - setzt ein 0 außer Kraft, falls beide angegeben sind.
' ' (ein Leerzeichen) Vor einer positiven Zahl (oder einer leeren Zeichenkette), die
durch eine vorzeichenbehaftete Umwandlung mit erzeugt wurde, soll ein Leerzeichen
erhalten bleiben.
+ 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 + übersteuert ein Leerzeichen, falls beide verwendet
werden.
Die obigen fünf Schalter werden vom C99-Standard definiert. Die Single UNIX Specification
spezifiziert einen weiteren Schalter.
' gibt für dezimale Umwandlungen (i, d, u, f, F, g, G) an, dass die Ausgabe mit dem
Tausender-Gruppierungszeichen gruppiert werden soll, wenn die Locale-Information
eines angibt (siehe setlocale(3)). Beachten Sie, dass viele Versionen von gcc(1)
diese Option nicht auswerten können und eine Warnung ausgeben werden. SUSv2
schließt %'F nicht mit ein, aber SUSv3 fügt es hinzu.
Glibc 2.2 fügt ein weiteres Schalterzeichen hinzu.
I Für dezimale Ganzzahlumwandlungen (i, d, u) 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.
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 m)
angegeben werden, um zu spezifizieren, dass die Feldbreite im nächsten (oder m-ten)
Argument gegeben ist, welches vom Type int sein muss. Eine negative Feldbreite wird als
Schalter '-' 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.
Genauigkeit
Eine optionale Genauigkeit in der Form eines Punkts ('.') gefolgt von einer optionalen
Dezimalzahl. Statt einer Dezimalzahl kann auch mittels »*« oder »*m$« (für irgendeine
Dezimalzahl m) angegeben werden, dass die Genauigkeit im nächsten (oder m-ten) Argument
gegeben ist, welches den Typ int haben muss. Falls die Genauigkeit einfach als '.'
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 d, i, o, u, x und X erscheinen, bzw. die Anzahl
der Ziffern nach dem Dezimaltrennzeichen bei a, A, e, E, f und F, die maximale Anzahl von
signifikanten Ziffern bei g und G oder die maximale Anzahl von auszugebenden Zeichen einer
Zeichenkette bei s und S.
Längenmodifikator
Im Folgenden steht »Ganzzahlumwandlung« für d, i, o, u, x oder X.
hh Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ signed char oder
unsigned char oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein
signed char-Argument.
h Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ short oder
unsigned short oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein
short-Argument.
l (ell) Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ long oder
unsigned long oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein
long-Argument oder eine folgende c-Umwandlung entspricht einem wint_t-Argument oder
eine folgende s-Umwandlung entspricht einem Zeiger auf ein wchar_t-Argument.
ll (ell-ell) Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ long
long oder unsigned long long oder eine folgende n-Umwandlung entspricht einem
Zeiger auf ein long long-Argument.
q Ein Synonym für ll. Dies ist eine aus BSD abgeleitete nicht standardisierte
Erweiterung, vermeiden sie die Verwendung in neuem Code.
L Eine folgende a-, A-, e-, E-, f-, F-, g- oder G-Umwandlung entspricht einem long
double-Argument. C99 erlaubt %LF, aber SUSv2 nicht.
j Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ intmax_t oder
uintmax_t oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein
intmax_t-Argument.
z Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ ssize_t oder
ssize_t oder eine folgende n-Umwandlung entspricht einem Zeiger auf ein
size_t-Argument.
Z Ein nicht standardisiertes Synonym für z, das von vor dem Auftauchen von z stammt.
Verwenden Sie es nicht in neuem Code.
t Eine folgende Ganzzahlumwandlung entspricht einem Argument vom Typ ptrdiff_t oder
eine folgende n-Umwandlung entspricht einem Zeiger auf ein ptrdiff_t-Argument.
SUSv3 spezifiziert alle oben genannten, außer den Modifikatoren, die explizit als nicht
standardisierte Erweiterungen vermerkt sind. SUSv2 kennt nur die Längenmodifikatoren h (in
hd, hi, ho, hx, hX, hn) und l (in ld, li, lo, lx, lX, ln, lc, ls) und L (in Le, LE, Lf,
Lg, LG).
Als eine nicht standardisierte Erweiterung behandelt die GNU-Implementierung ll und L als
Synonyme, so dass Sie llg (als Synonym für das standardmäßige Lg) und Ld (als Synonym für
das standardmäßige lld) schreiben können. Dies ist nicht portabel.
Umwandlungskennzeichner
Ein Zeichen, das den Typ der anzuwendenden Umwandlung angibt. Die Umwandlungskennzeichner
und ihre Bedeutung sind:
d, i Das int-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.
o, u, x, X
Das unsigned int-Argument wird in eine vorzeichenlose Oktal- (o), Dezimal- (u) oder
Hexadezimalzahl (x und X) umgewandelt. Die Buchstaben abcdef werden für
x-Umwandlungen benutzt; die Buchstaben ABCDEF für X-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.
e, E Das double-Argument wird gerundet und in die Form [-]d.ddde+-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 E-Umwandlung
verwendet den Buchstaben E (in Gegensatz zu e), um den Exponenten einzuleiten. Der
Exponent enthält immer mindestens zwei Ziffern; falls der Wert Null ist, ist der
Exponent 00.
f, F Das double-Argument wird gerundet und umgewandelt in dezimale Notation im Format
[-]ddd.ddd, 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.
(SUSv2 kennt F 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 F hinzu. Der C99-Standard spezifiziert »[-]inf« oder
»[-]infinity« für Unendlich sowie eine Zeichenkette beginnend mit »nan« für NaN im
Falle von f und entsprechen »[-]INF« oder »[-]INFINITY« oder »NAN« im Falle von F.)
g, G Das double-Argument wird in das Format f oder e (oder F oder E für die
G-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 e 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.
a, A (C99; nicht in SUSv2, aber in SUSv3 hinzugefügt) Für die a-Umwandlung wird das
double-Argument (unter Verwendung der Buchstaben abcdef) in hexadezimale Notation
der Form [-]0xh.hhhhp±d gebracht; für A werden dagegen das Präfix 0X, die
Buchstaben ABCDEF und das Exponententrennzeichen P 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 double 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.
c Wenn kein Modifikator l vorhanden ist, wird das int-Argument umgewandelt in einen
unsigned char und das resultierende Zeichen ausgegeben. Wenn ein l vorhanden ist,
wird das wint_t-Argument (wide character) mit einem Aufruf der Funktion wcrtomb(3)
zu einer Multibyte-Folge umgewandelt, mit der Konvertierung beginnend im initialen
Zustand, und die resultierende Multibyte-Zeichenkette wird ausgegeben.
s Wenn kein Modifikator l vorhanden ist, wird das const char *-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 terminierenden NULL-Bytes
('\0') ausgegeben; wenn eine Genauigkeit angegeben ist, werden nicht mehr Zeichen
als die angegebene Anzahl ausgegeben. Wenn eine Genauigkeit angegeben ist, braucht
kein NULL-Byte vorhanden zu sein; wenn die Genauigkeit nicht angegeben ist oder
größer als das Feld ist, muss das Feld ein abschließendes NULL-Byte enthalten.
Wenn ein l vorhanden ist, wird das const wchar_t *-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 wcrtomb(3),
beginnend im initialen Zustand vor dem ersten wide character), bis zu und
einschließlich des terminierenden wchar_t-Null-Zeichens. Die resultierenden
Multibyte-Zeichen werden bis zum (aber nicht einschließlich) des abschließenden
NULL-Bytes 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 Bytes angibt, nicht die Anzahl der wide characters oder
Bildschirmpositionen. Das Feld muss ein terminierendes wchar_t-Null-Zeichen
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.
C (Nicht in C99, aber in SUSv2, SUSv3 und SUSv4.) Synonym für lc. Nicht verwenden.
S (Nicht in C99, aber in SUSv2, SUSv3 und SUSv4.) Synonym für ls. Nicht verwenden.
p Das void *-Zeiger-Argument wird hexadezimal ausgegeben (wie bei %#x oder %#lx).
n Die Anzahl der bis dahin geschriebenen Zeichen wird in der Ganzzahl gespeichert,
die auf das korrespondierende Argument zeigt. Das Argument muss ein int * 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.
m (Glibc-Erweiterung, von uClibc und Musl unterstützt) Gibt die Ausgabe von
strerror(errno) aus; kein Argument erforderlich.
% Es wird ein '%' ausgegeben. Es wird kein Argument umgewandelt. Die vollständige
Umwandlungsanweisung ist '%%'.
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 NULL-Byte).
Die Funktionen snprintf() und vsnprintf() schreiben nicht mehr als size Byte
(einschließlich des abschließenden NULL-Bytes »\0«)). Falls die Ausgabe wegen dieser
Begrenzung gekürzt wurde, ist der Rückgabewert die Anzahl der Zeichen (ohne abschließendes
NULL-Byte), die bei ausreichendem Speicherplatz in die Ausgabe geschrieben worden wären.
Damit bedeutet ein Rückgabewert von size oder mehr, dass die Ausgabe gekürzt wurde. (Siehe
auch im Folgenden unter ANMERKUNGEN.)
Wenn bei der Ausgabe ein Fehler auftritt, wird ein negativer Wert zurückgegeben.
ATTRIBUTE
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
┌────────────────────────────────────────────────┬───────────────────────┬────────────────┐
│Schnittstelle │ Attribut │ Wert │
├────────────────────────────────────────────────┼───────────────────────┼────────────────┤
│printf(), fprintf(), sprintf(), snprintf(), │ Multithread-Fähigkeit │ MT-Safe locale │
│vprintf(), vfprintf(), vsprintf(), vsnprintf() │ │ │
└────────────────────────────────────────────────┴───────────────────────┴────────────────┘
KONFORM ZU
fprintf(), printf(), sprintf(), vprintf(), vfprintf(), vsprintf(): POSIX.1-2001,
POSIX.1-2008, C89, C99.
snprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99.
Die Funktionen dprintf() und vdprintf() waren ursprünglich GNU-Erweiterungen, die später
in POSIX.1-2008 standardisiert wurden.
Hinsichtlich des Rückgabewerts von snprintf() widersprechen sich SUSv2 und der
C99-Standard: wird snprintf() mit size=0 aufgerufen, dann fordert SUSv2 einen nicht
spezifizierten Rückgabewert kleiner als 1, während C99 es zulässt, dass str in diesem Fall
NULL ist, und (wie immer) den Rückgabewert als die Anzahl der Zeichen angibt, die bei
ausreichend großer Ausgabe-Zeichenkette geschrieben worden wären. POSIX.1-2001 und neuer
richten ihre Spezifikation von snprintf() an C99 aus.
Glibc 2.1 fügt die Längenmodifikatoren hh, j, t und z sowie die Umwandlungszeichen a und A
hinzu.
Glibc 2.2 fügt das Umwandlungszeichen F mit C99-Semantik sowie den Schalter l hinzu.
ANMERKUNGEN
Einige Programme verlassen sich leichtsinnig auf Code wie den folgenden
sprintf(buf, "%s etwas mehr Text", buf);
um Text an buf anzuhängen. Jedoch weisen die Standards explizit darauf hin, dass die
Ergebnisse undefiniert sind, wenn Quell- und Ziel-Puffer beim Aufruf von sprintf(),
snprintf(), vsprintf() und vsnprintf() überlappen. Abhängig von der verwendeten
gcc(1)-Version und den gewählten Compiler-Optionen erzeugen Aufrufe wie das obige Beispiel
nicht die erwarteten Ergebnisse.
Seit der Glibc-Version 2.1 ist die Implementierung der Funktionen snprintf() und
vsnprintf() 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.
FEHLER
Da sprintf() und vsprintf() 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 snprintf() und
vsnprintf() (oder asprintf(3) und vasprintf(3)).
Code wie beispielsweise printf(foo); weist häufig auf einen Fehler hin, da foo das Zeichen
»%« enthalten kann. Stammt foo von ungeprüfter Nutzereingabe, kann es »%n« enthalten und
veranlasst printf(), in den Speicher zu schreiben und erzeugt damit ein Sicherheitsloch.
BEISPIELE
Um Pi mit fünf Dezimalstellen auszugeben:
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
Um Datum und Zeit in der Form »Sunday, July 3, 10:02« auszugeben, wobei weekday und month
Zeiger auf Zeichenketten sind:
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
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:
#include <stdio.h>
fprintf(stdout, format,
weekday, month, day, hour, min);
wobei format von der Locale abhängt und möglicherweise die Argumente vertauscht. Mit dem
Wert
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
könnte dann »Sonntag, 3. Juli, 10:02« dabei herauskommen.
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):
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
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;
size = (size_t) n + 1; /* Ein zusätzliches Byte für '\0' */
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;
}
Bei Kürzungen in Glibc-Versionen vor 2.0.6 wird dies als ein Fehler aufgefasst und nicht
wohlwollend behandelt.
SIEHE AUCH
printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3),
wprintf(3), locale(5)
KOLOPHON
Diese Seite ist Teil der Veröffentlichung 5.13 des Projekts Linux-man-pages. 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/.
ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer
<Martin.E.Schauer@gmx.de>, Mario Blättermann <mario.blaettermann@gmail.com> und Helge
Kreutzmann <debian@helgefjell.de> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License
Version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ oder neuer bezüglich der Copyright-
Bedingungen. Es wird KEINE HAFTUNG übernommen.
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-
Mail an die Mailingliste der Übersetzer ⟨debian-l10n-german@lists.debian.org⟩.