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