Ubuntu Manpage: scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf

BEZEICHNUNG

       scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Anpassung des Eingabeformats

ÜBERSICHT

       #include <stdio.h>

       int scanf(const char *format, …);
       int fscanf(FILE *datenstrom, const char *format, …);
       int sscanf(const char *zeichenkette,
                  const char *format, …);

       #include <stdarg.h>

       int vscanf(const char *format, va_list ap);
       int vsscanf(const char *zeichenkette,
                   const char *format, va_list ap);
       int vfscanf(FILE *datenstrom,
                   const char *format, va_list ap);

   Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

       vscanf(), vsscanf(), vfscanf():
           _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

BESCHREIBUNG

Die Funktionenfamilie scanf() prüft Eingaben in Bezug auf ein format, wie es im Folgenden
beschrieben wird. Dieses Format darf Umwandlungsspezifikationen enthalten; die Ergebnisse
solcher Umwandlungen, falls vorhanden, werden an den Stellen gespeichert, auf die die
Zeiger-Argumente verweisen, die sich an das format halten. Jedes Zeiger-Argument muss
einen geeigneten Typ für den Rückgabewert durch die zugehörige Umwandlungsspezifikation
haben.

Falls die Anzahl der Umwandlungsspezifikation in format die Anzahl der Zeiger-Argumente
übersteigt, sind die Erbenisse undefiniert. Falls die Anzahl der Zeiger-Argumente die
Anzahl der Umwandlungsspezifikation übersteigt, werden die überzähligen Zeiger-Argumente
ausgewertet, aber ansonsten ignoriert.

Die Funktion scanf() liest Eingaben von der Standardeingabe stdin, fscanf liest Eingaben
von dem Datenstrom-Zeiger datenstrom und sscanf liest ihre Eingaben aus der Zeichenkette,
auf den zeichenkette zeigt.

Die Funktion vfscanf() verhält sich analog zu vfprintf(3) und liest Eingaben von dem
Datenstrom-Zeiger datenstrom, wobei eine variable Argumentliste von Zeigern benutzt wird
(siehe stdarg(3)). Die Funktion vscanf() liest eine variable Argumentliste von der
Standardeingabe und die Funktion vsscanf() liest sie aus einer Zeichenkette; diese sind
analog zu den Funktionen vprintf(3) beziehungsweise vsprintf(3).

Die Zeichenkette format besteht aus einer Abfolge von Richtlinien, die beschreiben, wie
die Abfolge der Eingabezeichen verarbeitet wird. Wenn das Verarbeiten einer Richtlinie
fehlschlägt, werden keine weiteren Eingaben gelesen und scanf() kehrt zurück. Ein
»Fehlschlagen« kann folgendes sein: input failure bedeutet, dass Eingabezeichen nicht
verfügbar sind. matching failure heißt, dass die Eingabe ungeeignet war (siehe unten).

Eine Richtlinie kann Folgendes sein:

• eine Abfolge von Leerräumen (Leerzeichen, Tabulator, Zeilenvorschub, etc.; siehe
isspace(3)). Diese Richtlinie passt auf jede Menge von Leerräumen, einschließlich
keinen in der Eingabe.

• ein normales Zeichen (d.h. ein anderes, als ein Leerraum oder »%«). Dieses Zeichen
muss exakt mit dem nächsten Zeichen der Eingabe übereinstimmen.

• eine Umwandlungsspezifikation, die mit dem Zeichen »%« (Prozent) beginnt. Eine
Abfolge von Zeichen wird gemäß dieser Spezifikation umgewandelt und das Ergebnis
wird in das zugehörige Zeiger-Argument platziert. Falls das nächste Element nicht
der Umwandlungsspezifikation entspricht, schlägt die Umwandlung fehl – dies ist ein
matching failure.

Jede Umwandlungsspezifikation in format fängt entweder mit dem Zeichen »%« an oder der
Zeichensequenz »%n$« (siehe unten für die Unterscheidung) gefolgt von:

• ein optionales »*«-Zeichen zur Unterdrückung der Zuweisung: scanf() liest die
Eingabe gemäß der Umwandlungsspezifikation, verwirft aber die Eingabe. Es wird kein
zugehöriges Zeiger-Argument benötigt und diese Spezifikation ist nicht in der
Anzahl der erfolgreichen Zuweisungen enthalten, die von scanf() zurückgegeben
werden.

• ein optionales Maskierungszeichen (') für dezimale Umwandlungen. Dies legt fest,
dass die Eingabezahl einen Tausendertrenner wie in der Kategorie LC_NUMERIC der
aktuellen Locale definiert enthalten kann (siehe setlocale(3)). Das
Maskierungszeichen kann dem »*«-Zuweisungsunterdrückungszeichen folgen oder ihm
vorangehen.

• ein optionales »m«-Zeichen. Dies wird mit Zeichenkettenumwandlungen benutzt (%s,
%c, %[) und entlastet den Aufrufenden von der Notwendigkeit, einen zugehörigen
Puffer zu reservieren, der die Eingabe erhält: Stattdessen reserviert scanf() einen
Puffer von ausreichender Größe und weist die Adresse dieses Puffers dem zugehörigen
Zeiger-Argument zu, das ein Zeiger auf eine char *-Variable sein sollte. (Diese
Variable muss nicht vor dem Aufruf initialisiert werden.) Der Aufrufende sollte
diesen Puffer danach mit free(3) freigeben, wenn er nicht länger benötigt wird.

• eine optionale dezimale Ganzzahl, die die maximale Feldbreite angibt. Das Lesen von
Zeichen stoppt entweder wenn dieses Maximum erreicht wurde oder wenn ein
unpassendes Zeichen gefunden wurde, je nachdem, was eher auftrat. Die meisten
Umwandlungen verwerfen Leerräume am Anfang (die Ausnahmen sind nachfolgend
vermerkt). Diese verworfenen Zeichen werden nicht bei der Berechnung der maximalen
Feldbreite mitgezählt. Eingabeumwandlung von Zeichenketten speichert ein
terminierendes Null-Byte (»\0«), um das Ende der Eingabe zu kennzeichnen; die
maximale Feldbreite enthält dieses Endezeichen nicht.

• ein optionales Typ-Änderungszeichen. Das Typ-Änderungszeichen l wird zum Beispiel
bei Ganzzahlumwandlungen, wie %d benutzt, um anzugeben, dass sich das zugehörige
Zeiger-Argument auf long int statt auf einen Zeiger vom Typ int bezieht.

• eine Umwandlungsspezifikation, die den Typ der durchzuführenden Eingabeumwandlung
angibt.

Die Umwandlungsspezifikationen in format haben zwei Formen, entweder mit »%« oder mit
»%n$« beginnend. Die beiden Formen sollten nicht in der gleichen Formatzeichenkette
gemischt werden, außer dass eine Zeichenkette die »%n$«-Spezifikationen enthält %% und %*
umfassen kann. Falls format »%«-Spezifikationen enthält, dann korrespondieren diese in der
Reihenfolge mit nachfolgenden Zeiger-Argumenten. In der Form »%n$« (die in POSIX.1-2001,
aber nicht in C99 spezifiziert ist), ist n eine dezimale Ganzzahl, die anzeigt, dass die
umgewandelte Eingabe an die Stelle platziert werden sollte, auf die sich das dem nten
Zeiger-Argument folgende format bezieht.

Umwandlungen
Die folgenden Typ-Änderungszeichen können in einer Umwandlungsspezifikation erscheinen:

h zeigt an, dass die Umwandlung entweder d, i, o, u, x, X oder n sein wird und der
nächste Zeiger ein Zeiger auf ein short int oder unsigned short int (statt int)
sein wird.

hh wie für h, aber der nächste Zeiger ist ein Zeiger auf ein signed char oder ein
unsigned char.

j wie für h, aber der nächste Zeiger ist ein Zeiger auf ein intmax_t oder ein
uintmax_t. Dieses Änderungszeichen wurde in C99 eingeführt.

l zeigt an, dass die Umwandlung entweder d, i, o, u, x, X oder n sein wird und der
nächste Zeiger ein Zeiger auf ein long int oder ein unsigned long int (statt int)
sein wird oder dass die Umwandlung entweder e, f oder g sein wird und der nächste
Zeiger ein Zeiger auf ein double (statt float ) sein wird. Die Angabe von zwei
l-Zeichen ist äquivalent zu L. Falls sie zusammen mit %c oder %s benutzt werden,
wird der zugehörige Parameter als ein Zeiger auf ein Wide-Character beziehungsweise
eine Wide-Character-Zeichenkette betrachtet.

L zeigt an, dass die Umwandlung entweder e, f oder g sein wird und der nächste Zeiger
ein Zeiger auf ein long double ist oder dass die Umwandlung entweder d, i, o, u
oder x sein wird und der nächste Zeiger ein Zeiger auf ein long long sein wird.

q ist äquivalent zu L. Dieses Spezifiakationssymbol existiert nicht in ANSI-C.

t wie für h, der nächste Zeiger ist aber ein Zeiger auf ein ptrdiff_t. Dieses
Änderungszeichen wurde in C99 eingeführt.

z wie für h, der nächste Zeiger ist aber ein Zeiger auf ein size_t. Dieses
Änderungszeichen wurde in C99 eingeführt.

Die folgenden Umwandlungsspezifikationen sind verfügbar:

% passt zum Buchstabensymbol »%«. Das heißt, %% im Formatstring passt zum einzelnen
Eingabezeichnen »%«. Es findet keine Umwandlung statt (aber Leerräume am Anfang
werden verworfen) und eine Zuweisung tritt nicht auf.

d passt zu einer optionalen vorzeichenbehafteten dezimalen Ganzzahl; der nächste
Zeiger muss ein Zeiger auf int sein.

D äquivalent zu ld; dies existiert nur aus Gründen der Rückwärtskompatibilität.
(Beachten Sie, dass dies daher nur in Libc4 der Fall ist. In Libc5 und Glibc wird
das %D stillschweigend ignoriert, was alte Programme zu mysteriösem Fehlschlagen
veranlasst.)

i passt zu einer optionalen vorzeichenbehafteten Ganzzahl; der nächste Zeiger muss
ein Zeiger auf int sein. Die Ganzzahl wird zur Basis 16 gelesen, wenn sie mit 0x
oder 0X beginnt, zur Basis 8, wenn sie mit 0 beginnt, anderenfalls zur Basis 10.
Nur Zeichen, die zur Basis passen, werden benutzt.

o passt zu einer vorzeichenlosen oktalen Ganzzahl; der nächste Zeiger muss ein Zeiger
auf ein unsigned int sein.

u passt zu einer vorzeichenlosen dezimalen Ganzzahl; der nächste Zeiger muss ein
Zeiger auf ein unsigned int sein.

x passt zu einer vorzeichenlosen hexadezimalen Ganzzahl; der nächste Zeiger muss ein
Zeiger auf ein unsigned int sein.

X äquivalent zu x

f passt zu einer optionalen vorzeichenbehafteten Fließkommazahl; der nächste Zeiger
muss ein Zeiger auf ein float sein.

e äquivalent zu f.

g äquivalent zu f.

E äquivalent zu f.

a (C99) äquivalent zu f.

s passt zu einer Zeichenfolge, die keinen Leerraum darstellt; der nächste Zeiger muss
Zeiger auf das erste Element eines Zeichenfelds sein, das groß genug ist, um die
Eingabesequenz und das abschließende Null-Byte (»\0«), das automatisch hinzugefügt
wird, aufnehmen zu können. Die Eingabezeichenkette stoppt an Leerräumen oder an der
maximalen Feldgröße, je nachdem, was zuerst auftritt.

c passt zu einer Zeichenfolge, deren Länge durch die maximale Feldgröße (Vorgabe 1)
angegeben wird; der nächste Zeiger muss ein Zeiger auf ein char sein und es muss
genug Platz für alle Zeichen vorhanden sein (es wird keine abschließende Null
angehängt.) Das übliche Überspringen der führenden Leerräume wird unterdrückt.
Benutzen Sie ein explizites Leerzeichen im Format, um Leerräume zu überspringen .

[ passt zu einer nicht leeren Abfolge von Zeichen aus der angegebenen
Zusammenstellung akzeptierter Zeichen; der nächste Zeiger muss ein Zeiger auf char
sein und genug Platz für alle Zeichen der Zeichenkette einschließlich
abschließendem Null-Byte bieten. Das übliche Überspringen der führenden Leerräume
wird unterdrückt. Die Zeichenkette soll aus Zeichen in einer (oder keiner)
besonderen Zusammenstellung bestehen; die Zusammenstellung wird durch die Zeichen
zwischen der öffnenden [ und schließenden ] Klammer definiert. Die Zusammenstellung
schließt jene Zeichen aus, wenn das erste Zeichen nach der öffnenden Klammer ein
Zirkumflex (^) ist. Um der Zusammenstellung eine schließende Klammer hinzuzufügen,
setzen Sie sie als erstes Zeichen nach der öffnenden Klammer oder dem Zirkumflex;
jede andere Position würde die Zusammenstellung beenden. Um einen Bindestrich
einzufügen, setzen Sie ihn als letztes Zeichen vor der schließenden Klammer am
Ende. [^]0-9-] bedeutet zum Beispiel, die Zusammenstellung »alles außer
schließender Klammer, null bis neun und Bindestrich«. Die Zeichenkette endet mit
dem Erscheinen eines nicht in der Zusammenstellung enthaltenen Zeichens (oder mit
einem enthaltenen Zirkumflex) oder wenn die Feldgröße erschöpft ist.

p passt zu einem Zeigerwert (wie durch »%p« in printf(3) ausgegeben); der nächste
Zeiger muss ein Zeiger auf void sein.

n es wird nichts erwartet; stattdessen wird die Anzahl der Zeichen, die bis jetzt
eingelesen wurden, im nächsten Zeiger gespeichert, welcher ein Zeiger auf int sein
muss. Dies ist keine Umwandlung und erhöht nicht die von der Funktion
zurückgegebene Anzahl. Die Zuweisung kann durch das Zuweisungsunterdrückungszeichen
* unterdrückt werden, die Auswirkung auf den Rückgabewert ist jedoch nicht
definiert. Daher sollten keine %*n-Umwandlungen benutzt werden.

RÜCKGABEWERT

       Bei Erfolg geben diese Funktionen die Anzahl der Eingabeelemente zurück,  die  erfolgreich
       übereinstimmten und zugewiesen wurden. Dies können weniger sein, als bereitgestellt wurden
       oder null, wenn ein früherer Abgleich scheiterte.

       Der Wert EOF wird zurückgegeben, wenn das Ende der Eingabe erreicht wird,  bevor  entweder
       die erste erfolgreiche Umwandlung oder das erste Fehlschlagen eines Abgleichs auftrat. EOF
       wird  auch  zurückgegeben,  wenn  ein  Lesefehler  auftritt.  In  diesem  Fall  wird   die
       Fehleranzeige  für  den Datenstrom gesetzt (siehe ferror(3)) und errno so gesetzt, dass es
       den Fehler angibt.

FEHLER

       EAGAIN Der Dateideskriptor,  der  datenstrom  zugrundeliegt,  ist  als  nicht  blockierend
              gekennzeichnet und die Leseaktion würde blockieren.

       EBADF  Der  Dateideskriptor,  der  datenstrom  zugrundeliegt,  ist ungültig oder nicht zum
              Lesen geöffnet.

       EILSEQ Eingabebyte-Abfolge bildet kein gültiges Zeichen

       EINTR  Die Leseaktion wurde durch ein Signal unterbrochen; siehe signal(7).

       EINVAL nicht genug Argumente oder format ist NULL

       ENOMEM Speicher aufgebraucht.

       ERANGE Das Ergebnis einer Ganzzahl-Umwandlung würde die Größe überschreiten,  die  in  dem
              zugehörigen Ganzzahl-Typ gespeichert werden könnte.

ATTRIBUTE

       Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.

       ┌─────────────────────┬───────────────────────┬────────────────┐
       │Schnittstelle        │ Attribut              │ Wert           │
       ├─────────────────────┼───────────────────────┼────────────────┤
       │scanf(), fscanf(),   │ Multithread-Fähigkeit │ MT-Safe locale │
       │sscanf(), vscanf(),  │                       │                │
       │vsscanf(), vfscanf() │                       │                │
       └─────────────────────┴───────────────────────┴────────────────┘

KONFORM ZU

       Die  Funktionen  fscanf(), scanf() und sscanf() sind konform zu c89, C99 und POSIX.1-2001.
       Diese Vorgaben spezifizieren nicht den Fehler ERANGE.

       Das Spezifikationssymbol q ist die 4.4BSD-Schreibweise für long long, während ll oder  die
       Benutzung von L in Ganzzahlumwandlungen die GNU-Schreibweise ist.

       Die  Linuxversion  dieser  Funktionen  basiert auf der GNU-Bibliothek libio Eine präzisere
       Beschreibung findet sich in der info-Dokumentation von GNU libc (glibc-1.08).

ANMERKUNGEN

Der Zuweisungs- und Reservierungsmodifikator »a«
Ursprünglich unterstützte die GNU-C-Bibliothek die dynamische Reservierung für
Eingabezeichenketten (als eine Nichtstandarderweiterung) über das Zeichen a. (Diese
Funktionalität ist bis mindestens Glibc 2.0 zurück verfügbar.) Daher könnte jemand das
Folgende schreiben, um scanf() einen Puffer für eine Eingabezeichenkette reservieren zu
lassen. Ein Zeiger auf diesen Puffer wird in *buf zurückgegeben:

char *buf;
scanf("%as", &buf);

Die Verwendung des Buchstabens a für diesen Zweck war problematisch, da a auch im
ISO-C-Standard als andere Bezeichnung für f (Fließkommaeingabe) spezifiziert ist.
POSIX.1-2008 spezifiziert stattdessen den Modifikator m für die Zuweisungsreservierung
(wie oben unter BESCHREIBUNG dokumentiert).

Beachten Sie, dass der Modifikator a nicht verfügbar ist, falls das Programm mit gcc
-std=c99 oder gcc -D_ISOC99_SOURCE kompiliert wurde (außer wenn auch _GNU_SOURCE angegeben
wurde). In diesem Fall wird a als Spezifikationssymbol für Fließkommazahlen interpretiert
(siehe oben).

Ab Version 2.7 wurde Glibc Unterstützung für dem Modifikator m hinzugefügt. Neue Programme
sollten diesen Modifikator anstelle von a benutzen.

Neben der Standardisierung durch POSIX, hat der Modifikator m auch die folgenden Vorteile
gegenüber der Verwendung von a:

* Es könnte auch auf %c-Umwandlungsspezifikationen angewandt werden (z.B. %3mc).

* Es vermeidet Mehrdeutigkeit bezüglich der Umwandlungsspezifikation für Fließkommazahlen
%a (und wird nicht von gcc -std=c99 etc. beeinflusst).

FEHLER

       Alle   Funktionen  sind  vollkommen  konform  zu  C89,  stellen  jedoch  die  zusätzlichen
       Spezifikationssymbole q und a sowie ein zusätzliches Verhalten der Spezifikationssymbole L
       und  l  zur Verfügung. Letzteres kann als Fehler angesehen werden, da es das Verhalten der
       Spezifikationssymbole verändert, die in C89 definiert sind.

       Einige Kombinationen von Typänderungssymbolen und  Umwandlungsspezifikationen,  die  durch
       ANSI-C  definiert sind, sind sinnlos (z.B. %Ld). Während sie ein wohldefiniertes Verhalten
       unter Linux haben, braucht dies auf anderen Architekturen nicht der Fall  zu  sein.  Daher
       ist  es  gewöhnlich  besser  Änderungssymbole  zu  benutzen,  die  gar  nicht durch ANSI-C
       definiert sind, also q anstelle von L in Kombination mit der Umwandlungen d, i,  o,  u,  x
       und X oder ll.

       Die Benutzung von q ist nicht die gleiche wie auf 4.4BSD, da sie in Fließkommaumwandlungen
       äquivalent zu L benutzt werden kann.

BEISPIEL

       Um den Bezeichner für die dynamische Reservierungsanpassung zu verwenden,  geben  Sie  als
       Längenumwandler  m  an (also %ms oder %m[Bereich]). Der Aufrufende muss die zurückgegebene
       Zeichenkette mit free(3), wie im folgenden Beispiel, freigeben:

           char *p;
           int n;

           errno = 0;
           n = scanf("%m[a-z]", &p);
           if (n == 1) {
               printf("read: %s\n", p);
               free(p);
           } else if (errno != 0) {
               perror("scanf");
           } else {
               fprintf(stderr, "Keine passenden Zeichen\n");
           }

       Wie im vorstehenden Beispiel gezeigt, ist es nur nötig free(3) aufzurufen, wenn der Aufruf
       von scanf() eine Zeichenkette erfolgreich gelesen hat.

SIEHE AUCH

       getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)

KOLOPHON

       Diese  Seite  ist  Teil  der  Veröffentlichung  4.15  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 Patrick Rother <krd@gulu.net>,
       Chris Leick <c.leick@vollbio.de> und Helge Kreutzmann <debian@helgefjell.de> erstellt.

       Diese Übersetzung ist Freie Dokumentation;  lesen  Sie  die  GNU  General  Public  License
       Version   3  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 <debian-l10n-german@lists.debian.org>.