Provided by: manpages-de-dev_0.10-1_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():
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L;
           oder cc -std=c99

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      »a«-Zeichen.      Dies     wird     mit
              Zeichenkettenumwandlungen benutzt 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. 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).

       ·      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
              Null-Endezeichen  (»\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 ein Zeichenfeld  sein,  das  groß
              genueg   ist.   um  die  Eingabesequenz  und  das  abschließende
              Null-Zeichen (»\0«) 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
              Feldgre  (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
              schliet  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, obwohl sie durch das Zeichen zum  Unterdrücken
              von  Zuweisungen * unterdrückt werden kann. Der C-Standard sagt:
              »Die Ausführung einer %n-Richtlinie erhöht nicht die Anzahl  der
              Zuweisungen, die bei Fertigstellung der Ausführung zurückgegeben
              werden«, aber die Berichtigung scheint dem zu widersprechen.  Es
              ist  wahrscheinlich ratsam, keine Annahmen über die Auswirkungen
              von %n-Umwandlungen auf den Rückgabewert zu treffen.

RÜCKGABEWERT

       Diese Funktionen geben  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 Leseoperation würde blocken.

       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 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   würde  die  Größe
              überschreiten, die in dem zugehörigen  Ganzzahl-Typ  gespeichert
              werden könnte.

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

       Die   GNU-C-Bibliothek   unterstützt   eine    nicht    standardisierte
       Erweiterung,  die die Bibliothek veranlasst dynamisch eine Zeichenkette
       von ausreichender  Größe  für  Eingabezeichenketten  und  die  %s-  und
       %a[Bereich]-Umwandlungsspezifikationen  zu  reservieren.  Um von dieser
       Funktion Gebrauch zu machen, geben Sie als Längenänderungszeichen a  an
       (also  %as  oder  %a[range]).  Der  Aufrufende  muss die zurückgegebene
       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  nötig  free(3)
       aufzurufen,  wenn  der Aufruf von scanf() eine Zeichenkette erfolgreich
       gelesen hat.

       Das Änderungszeichen a ist nicht verfügbar, wenn 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).

       Seit  Version  2.7 stellt Glibc außerdem das Änderungszeichen m für den
       gleichen Zweck wie das Änderungszeichen a bereit. Das  Änderungszeichen
       m hat die folgenden Vorteile:

       * 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).

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

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.

SIEHE AUCH

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

KOLOPHON

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

ÜBERSETZUNG

       Die  deutsche Übersetzung dieser Handbuchseite wurde von Patrick Rother
       <krd@gulu.net> und Chris Leick <c.leick@vollbio.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>.