Provided by: manpages-de-dev_2.15-1build1_all bug

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.

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

       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.

       ┌─────────────────────┬───────────────────────┬────────────────┐
       │SchnittstelleAttributWert           │
       ├─────────────────────┼───────────────────────┼────────────────┤
       │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.

BEISPIEL

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