Provided by: manpages-de-dev_1.4-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  »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.

       •      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ß genug ist, um die Eingabesequenz und das abschließende Null-Byte (»\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 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.

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ützte  den  Bezeichner  für  die  dynamische  Reservierungsanpassung   (als
       Nicht-Standarderweiterung)  über  das  Zeichen  a.  Diese Funktionalität scheint bis mindestens Glibc 2.0
       zurück verfügbar zu sein.

       Er 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 im POSIX.1-2008-Standard 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.

BEISPIEL

       Um den Bezeichner für die dynamische Reservierungsanpassung zu verwenden, geben Sie als Längenumwandler 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

       This  page  is  part  of  release  3.54 of the Linux man-pages project. A description of the project, and
       information about reporting bugs, can be found at 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>.