jammy (3) vscanf.3.gz

Provided by: manpages-de-dev_4.13-4_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  der  zugehörigen
       Umwandlungsspezifikation haben.

       Falls  die Anzahl der Umwandlungsspezifikation in format die Anzahl der Zeiger-Argumente übersteigt, sind
       die Ergebnisse 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  die
       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:

       •      einem optionalen »*«-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.

       •      einem  optionalen  englischen  Anführungszeichen (') für dezimale Umwandlungen. Dies gibt an, 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.

       •      einem optionalen »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.

       •      einer  optionalen  dezimalen  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.

       •      einem   optionalen   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 statt auf einen Zeiger vom Typ int bezieht.

       •      einem 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 oder unsigned short (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 oder ein unsigned long (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.

       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  optional  0x  oder  0X  vorangestellt
              werden kann, was ignoriert wird); 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  Menge  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  ausschließlich  aus  Zeichen  bestehen,  die in einer
              bestimmten Menge (nicht) enthalten sind; die Menge wird durch die Zeichen zwischen der öffnenden [
              und  schließenden ] Klammer definiert. Die Menge schließt jene Zeichen aus, wenn das erste Zeichen
              nach der öffnenden Klammer  ein  Zirkumflex  (^)  ist.  Um  der  Menge  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 Menge 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 Menge
              »alles außer schließender Klammer, null bis neun und Bindestrich«. Die Zeichenkette endet mit  dem
              Erscheinen  eines  nicht in der Menge 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  »matching
       failure« auftrat.

       Der  Wert  EOF  wird  zurückgegeben,  wenn  das  Ende der Eingabe erreicht wird, bevor entweder die erste
       erfolgreiche Umwandlung oder ein »matching failure«  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.

BEISPIELE

       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.10  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
       ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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  die
       Mailingliste der Übersetzer ⟨debian-l10n-german@lists.debian.org⟩.