Provided by: manpages-de-dev_4.15.0-9_all bug

BEZEICHNUNG

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

ÜBERSICHT

       #include <stdio.h>

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

       #include <stdarg.h>

       int vscanf(const char *restrict format, va_list ap);
       int vfscanf(FILE *restrict datenstrom,
                  const char *restrict format, va_list ap);
       int vsscanf(const char *restrict zeichenkette,
                  const char *restrict 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 der zugehörigen Umwandlungsspezifikation haben.

       Falls  die  Anzahl  der Umwandlungsspezifikation in format die Anzahl der Zeiger-Argumente
       übersteigt, sind die Ergebnisse 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 die 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:

       •      einem optionalen »*«-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.

       •      einem optionalen englischen Anführungszeichen (') 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.

       •      einem optionalen »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.

       •      einer optionalen dezimalen 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.

       •      einem optionalen 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.

       •      einem  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 Menge
              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  ausschließlich  aus  Zeichen  bestehen, die in einer bestimmten
              Menge (nicht) enthalten sind;  die  Menge  wird  durch  die  Zeichen  zwischen  der
              öffnenden  [  und schließenden ] Klammer definiert. Die Menge schließt jene Zeichen
              aus, wenn das erste Zeichen nach der öffnenden Klammer ein Zirkumflex (^)  ist.  Um
              der  Menge 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
              Menge  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  Menge
              »alles außer schließender Klammer, null bis neun und Bindestrich«. Die Zeichenkette
              endet mit dem Erscheinen eines nicht in der Menge 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 oder eine Variante, deren Größe auf den (optional)  angegebenen,  ganzzahligen
              Längenmodifikator  passen  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 »matching failure« auftrat.

       Der  Wert  EOF wird zurückgegeben, wenn das Ende der Eingabe erreicht wird, bevor entweder
       die erste erfolgreiche Umwandlung oder ein  »matching  failure«  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.

       ┌────────────────────────────────────────────────┬───────────────────────┬────────────────┐
       │SchnittstelleAttributWert           │
       ├────────────────────────────────────────────────┼───────────────────────┼────────────────┤
       │scanf(), fscanf(), sscanf(), vscanf(),          │ Multithread-Fähigkeit │ MT-Safe locale │
       │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.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  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⟩.