scanf

SCANF(3)                    Linux-Programmierhandbuch                   SCANF(3)



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 gibt an, 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 statt
              auf einen Zeiger vom Typ int bezieht.

       •      ein Umwandlungskennzeichner, der 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 oder
              unsigned short (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 oder ein
              unsigned long (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. Dieser Kennzeichner existiert in ANSI-C
              nicht.

       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 Umwandlungskennzeichner 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.

       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
              optional 0x oder 0X vorangestellt werden kann, was ignoriert
              wird); 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.

       Der Kennzeichner 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
       Kennzeichner 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-Umwandlungskennzeichner angewandt werden (z.B.
         %3mc).

       * Es vermeidet Mehrdeutigkeit bezüglich der Umwandlungskennzeichner 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 Kennzeichner q und a sowie ein zusätzliches Verhalten des
       Kennzeichners L und l zur Verfügung. Letzteres kann als Fehler angesehen
       werden, da es das Verhalten der Kennzeichner verändert, die in C89
       definiert sind.

       Einige Kombinationen von Typänderungssymbolen und
       Umwandlungskennzeichner, 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.

BEISPIELE
       Um den Kennzeichner für die dynamische Reservierungsumwandlung zu
       verwenden, geben Sie als Längenmodifikator 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 5.10 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 ⟨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⟩.



GNU                              13. August 2020                        SCANF(3)