Provided by: manpages-de-dev_0.10-1_all bug

BEZEICHNUNG

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

"UBERSICHT

       #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():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           oder cc -std=c99

BESCHREIBUNG

       Die  Funktionenfamilie  scanf() pruft 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  fur  den  Ruckgabewert
       durch die zugehorige Umwandlungsspezifikation haben.

       Falls  die Anzahl der Umwandlungsspezifikation in format die Anzahl der
       Zeiger-Argumente ubersteigt, sind die Erbenisse undefiniert. Falls  die
       Anzahl  der  Zeiger-Argumente  die  Anzahl der Umwandlungsspezifikation
       ubersteigt, werden die uberzahligen 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()  verhalt  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  fehlschlagt,  werden  keine  weiteren
       Eingaben  gelesen  und  scanf() kehrt zuruck. Ein >>Fehlschlagen<< kann
       folgendes sein:  input  failure  bedeutet,  dass  Eingabezeichen  nicht
       verfugbar sind. matching failure heiBt, dass die Eingabe ungeeignet war
       (siehe unten).

       Eine Richtlinie kann Folgendes sein:

       o      eine   Abfolge   von   Leerraumen    (Leerzeichen,    Tabulator,
              Zeilenvorschub,  etc.; siehe isspace(3)). Diese Richtlinie passt
              auf jede Menge von  Leerraumen,  einschlieBlich  keinen  in  der
              Eingabe.

       o      ein  normales  Zeichen  (d.h. ein anderes, als ein Leerraum oder
              >>%<<). Dieses Zeichen muss exakt mit dem nachsten  Zeichen  der
              Eingabe ubereinstimmen.

       o      eine   Umwandlungsspezifikation,   die  mit  dem  Zeichen  >>%<<
              (Prozent) beginnt. Eine Abfolge von Zeichen  wird  gemaB  dieser
              Spezifikation   umgewandelt   und   das  Ergebnis  wird  in  das
              zugehorige Zeiger-Argument platziert. Falls das nachste  Element
              nicht   der  Umwandlungsspezifikation  entspricht,  schlagt  die
              Umwandlung fehl - dies ist ein matching failure.

       Jede Umwandlungsspezifikation in format fangt entweder mit dem  Zeichen
       >>%<<   an  oder  der  Zeichensequenz  >>%n$<<  (siehe  unten  fur  die
       Unterscheidung) gefolgt von:

       o      ein optionales >>*<<-Zeichen zur  Unterdruckung  der  Zuweisung:
              scanf()  liest  die  Eingabe gemaB der Umwandlungsspezifikation,
              verwirft  aber   die   Eingabe.   Es   wird   kein   zugehoriges
              Zeiger-Argument  benotigt  und  diese Spezifikation ist nicht in
              der Anzahl der  erfolgreichen  Zuweisungen  enthalten,  die  von
              scanf() zuruckgegeben werden.

       o      ein      optionales     >>a<<-Zeichen.     Dies     wird     mit
              Zeichenkettenumwandlungen benutzt und entlastet den  Aufrufenden
              von  der  Notwendigkeit einen zugehorigen Puffer zu reservieren,
              der die Eingabe erhalt:  Stattdessen  reserviert  scanf()  einen
              Puffer  von  ausreichender  GroBe  und  weist die Adresse dieses
              Puffers dem zugehorigen 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 langer
              benotigt wird. Dies ist eine GNU-Erweiterung; C99 verwendet  das
              Zeichen  >>a<<  als Umwandlungs-Speifikationssymbol (und es kann
              auch in der GNU-Implementierung als solches benutzt werden).

       o      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 Leerraume am Anfang (die  Ausnahmen  sind
              nachfolgend  vermerkt).  Diese  verworfenen Zeichen werden nicht
              bei  der  Berechnung  der   maximalen   Feldbreite   mitgezahlt.
              Eingabeumwandlung     von     Zeichenketten     speichert    ein
              Null-Endezeichen  (>>\0<<),  um  das   Ende   der   Eingabe   zu
              kennzeichnen; die maximale Feldbreite enthalt dieses Endezeichen
              nicht.

       o      ein optionales Typ-"Anderungszeichen. Das Typ-Anderungszeichen  l
              wird  zum  Beispiel bei Ganzzahlumwandlungen, wie %d benutzt, um
              anzugeben, dass sich das zugehorige Zeiger-Argument auf long int
              statt auf einen Zeiger vom Typ int bezieht.

       o      eine  Umwandlungsspezifikation, die den Typ der durchzufuhrenden
              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,  auBer  dass  eine
       Zeichenkette  die  >>%n$<<-Spezifikationen  enthalt  %% und %* umfassen
       kann. Falls format >>%<<-Spezifikationen enthalt, 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-"Anderungszeichen     konnen     in     einer
       Umwandlungsspezifikation erscheinen:

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

       hh     wie fur h, aber der nachste Zeiger ist ein Zeiger auf ein signed
              char oder ein unsigned char.

       j      wie  fur  h,  aber  der  nachste  Zeiger  ist ein Zeiger auf ein
              intmax_t oder ein uintmax_t. Dieses  Anderungszeichen  wurde  in
              C99 eingefuhrt.

       l      zeigt  an,  dass die Umwandlung entweder d, i, o, u, x, X oder n
              sein wird und der nachste 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 nachste Zeiger
              ein  Zeiger  auf ein double (statt float ) sein wird. Die Angabe
              von zwei l-Zeichen ist aquivalent zu L. Falls sie  zusammen  mit
              %c oder %s benutzt werden, wird der zugehorige 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 nachste Zeiger ein Zeiger auf ein long double ist oder  dass
              die  Umwandlung  entweder  d,  i,  o, u oder x sein wird und der
              nachste Zeiger ein Zeiger auf ein long long sein wird.

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

       t      wie  fur  h,  der  nachste  Zeiger  ist  aber ein Zeiger auf ein
              ptrdiff_t. Dieses Anderungszeichen wurde in C99 eingefuhrt.

       z      wie fur h, der nachste  Zeiger  ist  aber  ein  Zeiger  auf  ein
              size_t. Dieses Anderungszeichen wurde in C99 eingefuhrt.

       Die folgenden Umwandlungsspezifikationen sind verfugbar:

       %      passt  zum Buchstabensymbol >>%<<. Das heiBt, %% im Formatstring
              passt zum  einzelnen  Eingabezeichnen  >>%<<.  Es  findet  keine
              Umwandlung statt (aber Leerraume am Anfang werden verworfen) und
              eine Zuweisung tritt nicht auf.

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

       D      aquivalent   zu   ld;   dies   existiert  nur  aus  Grunden  der
              Ruckwartskompatibilitat. (Beachten Sie, dass dies daher  nur  in
              Libc4   der   Fall   ist.   In  Libc5  und  Glibc  wird  das  %D
              stillschweigend ignoriert, was  alte  Programme  zu  mysteriosem
              Fehlschlagen veranlasst.)

       i      passt  zu  einer  optionalen  vorzeichenbehafteten Ganzzahl; der
              nachste 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 nachste
              Zeiger muss ein Zeiger auf ein unsigned int sein.

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

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

       X      aquivalent zu x

       f      passt zu einer optionalen  vorzeichenbehafteten  FlieBkommazahl;
              der nachste Zeiger muss ein Zeiger auf ein float sein.

       e      aquivalent zu f.

       g      aquivalent zu f.

       E      aquivalent zu f.

       a      (C99) aquivalent zu f.

       s      passt  zu einer Zeichenfolge, die keinen Leerraum darstellt; der
              nachste Zeiger muss Zeiger auf ein Zeichenfeld  sein,  das  groB
              genueg   ist.   um  die  Eingabesequenz  und  das  abschlieBende
              Null-Zeichen    (>>\0<<)    aufnehmen     zu     konnen.     Die
              Eingabezeichenkette  stoppt  an Leerraumen oder an der maximalen
              FeldgroBe, je nachdem, was zuerst auftritt.

       c      passt zu einer Zeichenfolge,  deren  Lange  durch  die  maximale
              Feldgr"oBe  (Vorgabe  1)  angegeben wird; der nachste Zeiger muss
              ein Zeiger auf ein char sein und es muss genug  Platz  fur  alle
              Zeichen   vorhanden  sein  (es  wird  keine  abschlieBende  Null
              angehangt.) Das ubliche  Uberspringen  der  fuhrenden  Leerraume
              wird  unterdruckt.  Benutzen  Sie  ein explizites Leerzeichen im
              Format, um Leerraume zu uberspringen .

       [      passt  zu  einer  nicht  leeren  Abfolge  von  Zeichen  aus  der
              angegebenen  Zusammenstellung  akzeptierter Zeichen; der nachste
              Zeiger muss ein Zeiger auf char sein und genug  Platz  fur  alle
              Zeichen der Zeichenkette einschlieBlich abschlieBendem Null-Byte
              bieten. Das ubliche Uberspringen der  fuhrenden  Leerraume  wird
              unterdruckt.  Die  Zeichenkette  soll aus Zeichen in einer (oder
              keiner)    besonderen     Zusammenstellung     bestehen;     die
              Zusammenstellung wird durch die Zeichen zwischen der offnenden [
              und  schlieBenden  ]  Klammer  definiert.  Die  Zusammenstellung
              schlieBt  jene  Zeichen  aus,  wenn  das  erste Zeichen nach der
              offnenden   Klammer   ein   Zirkumflex   (^)   ist.    Um    der
              Zusammenstellung  eine  schlieBende Klammer hinzuzufugen, setzen
              Sie sie als erstes Zeichen nach der offnenden Klammer  oder  dem
              Zirkumflex;  jede  andere  Position  wurde  die Zusammenstellung
              beenden. Um einen Bindestrich einzufugen,  setzen  Sie  ihn  als
              letztes  Zeichen  vor der schlieBenden Klammer am Ende. [^]0-9-]
              bedeutet  zum  Beispiel,  die  Zusammenstellung  >>alles   auBer
              schlieBender  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 FeldgroBe erschopft ist.

       p      passt  zu  einem  Zeigerwert  (wie  durch  >>%p<<  in  printf(3)
              ausgegeben); der nachste Zeiger muss ein Zeiger auf void sein.

       n      es  wird  nichts  erwartet;  stattdessen  wird  die  Anzahl  der
              Zeichen, die bis jetzt eingelesen  wurden,  im  nachsten  Zeiger
              gespeichert,  welcher  ein  Zeiger  auf  int sein muss. Dies ist
              keine Umwandlung, obwohl sie durch das Zeichen zum  Unterdrucken
              von  Zuweisungen * unterdruckt werden kann. Der C-Standard sagt:
              >>Die Ausfuhrung einer %n-Richtlinie erhoht nicht die Anzahl der
              Zuweisungen, die bei Fertigstellung der Ausfuhrung zuruckgegeben
              werden<<, aber die Berichtigung scheint dem zu widersprechen. Es
              ist  wahrscheinlich ratsam, keine Annahmen uber die Auswirkungen
              von %n-Umwandlungen auf den Ruckgabewert zu treffen.

R"UCKGABEWERT

       Diese Funktionen geben  die  Anzahl  der  Eingabeelemente  zuruck,  die
       erfolgreich  ubereinstimmten und zugewiesen wurden. Dies konnen weniger
       sein, als bereitgestellt wurden oder null, wenn ein  fruherer  Abgleich
       scheiterte.

       Der  Wert  EOF  wird  zuruckgegeben, wenn das Ende der Eingabe erreicht
       wird, bevor entweder die erste erfolgreiche Umwandlung oder  das  erste
       Fehlschlagen eines Abgleichs auftrat. EOF wird auch zuruckgegeben, wenn
       ein Lesefehler auftritt. In diesem Fall wird die Fehleranzeige fur  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 Leseoperation wurde blocken.

       EBADF  Der  Dateideskriptor, der datenstrom zugrundeliegt, ist ungultig
              oder nicht zum Lesen geoffnet.

       EILSEQ Eingabebyte-Abfolge bildet kein gultiges Zeichen

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

       EINVAL nicht genug Argumente oder format ist NULL

       ENOMEM Platz im Hauptspeicher reicht nicht aus

       ERANGE Das   Ergebnis   einer   Ganzzahl-Umwandlung   wurde  die  GroBe
              uberschreiten, die in dem zugehorigen  Ganzzahl-Typ  gespeichert
              werden konnte.

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 fur  long  long,
       wahrend  ll  oder  die  Benutzung  von  L  in  Ganzzahlumwandlungen die
       GNU-Schreibweise ist.

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

ANMERKUNGEN

       Die   GNU-C-Bibliothek   unterstutzt   eine    nicht    standardisierte
       Erweiterung,  die die Bibliothek veranlasst dynamisch eine Zeichenkette
       von ausreichender  GroBe  fur  Eingabezeichenketten  und  die  %s-  und
       %a[Bereich]-Umwandlungsspezifikationen  zu  reservieren.  Um von dieser
       Funktion Gebrauch zu machen, geben Sie als Langenanderungszeichen a  an
       (also  %as  oder  %a[range]).  Der  Aufrufende  muss die zuruckgegebene
       Zeichenkette mit free(3), wie im folgenden Beispiel freigeben:

           char *p;
           int n;

           errno = 0;
           n = scanf("%a[a-z]", &p);
           if (n == 1) {
               printf("gelesen: %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  notig  free(3)
       aufzurufen,  wenn  der Aufruf von scanf() eine Zeichenkette erfolgreich
       gelesen hat.

       Das Anderungszeichen a ist nicht verfugbar, wenn das Programm  mit  gcc
       -std=c99  oder  gcc  -D_ISOC99_SOURCE kompiliert wurde (auBer wenn auch
       _GNU_SOURCE   angegeben   wurde).   In   diesem   Fall   wird   a   als
       Spezifikationssymbol fur FlieBkommazahlen interpretiert (siehe oben).

       Seit  Version  2.7 stellt Glibc auBerdem das Anderungszeichen m fur den
       gleichen Zweck wie das Anderungszeichen a bereit. Das  Anderungszeichen
       m hat die folgenden Vorteile:

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

       * Es vermeidet Mehrdeutigkeit  bezuglich  der  Umwandlungsspezifikation
         fur  FlieBkommazahlen  %a  (und  wird  nicht  von  gcc  -std=c99 etc.
         beeinflusst).

       * Es ist in  der  bevorstehenden  Uberarbeitung  des  POSIX.1-Standards
         spezifiziert.

FEHLER

       Alle  Funktionen  sind  vollkommen  konform  zu C89, stellen jedoch die
       zusatzlichen Spezifikationssymbole  q  und  a  sowie  ein  zusatzliches
       Verhalten  der  Spezifikationssymbole  L und l zur Verfugung. Letzteres
       kann  als  Fehler  angesehen  werden,   da   es   das   Verhalten   der
       Spezifikationssymbole verandert, die in C89 definiert sind.

       Einige       Kombinationen       von      Typanderungssymbolen      und
       Umwandlungsspezifikationen,  die  durch  ANSI-C  definiert  sind,  sind
       sinnlos  (z.B.  %Ld).  Wahrend  sie ein wohldefiniertes Verhalten unter
       Linux haben, braucht dies auf anderen Architekturen nicht der  Fall  zu
       sein.  Daher ist es gewohnlich besser Anderungssymbole 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
       FlieBkommaumwandlungen aquivalent zu L benutzt werden kann.

SIEHE AUCH

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

KOLOPHON

       Diese  Seite  ist  Teil  der   Veroffentlichung   3.32   des   Projekts
       Linux-man-pages.  Eine Beschreibung des Projekts und Informationen, wie
       Fehler    gemeldet     werden     konnen,     finden     sich     unter
       http://www.kernel.org/doc/man-pages/.

"UBERSETZUNG

       Die  deutsche Ubersetzung dieser Handbuchseite wurde von Patrick Rother
       <krd@gulu.net> und Chris Leick <c.leick@vollbio.de> erstellt.

       Diese Ubersetzung ist Freie Dokumentation; lesen Sie  die  GNU  General
       Public   License   Version   3  oder  neuer  bezuglich  der  Copyright-
       Bedingungen. Es wird KEINE HAFTUNG ubernommen.

       Wenn  Sie  Fehler  in  der  Ubersetzung  dieser  Handbuchseite  finden,
       schicken     Sie     bitte     eine     E-Mail     an     <debian-l10n-
       german@lists.debian.org>.