.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)scanf.3	6.14 (Berkeley) 1/8/93
.\"
.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
.\" modified to resemble the GNU libio setup used in the Linux libc 
.\" used in versions 4.x (x>4) and 5   Helmut.Geyer@iwr.uni-heidelberg.de
.\"
.\" Translated to German Sun Feb 23 1997 by Patrick Rother <krd@gulu.net>
.\"
.TH SCANF 3  "3. Januar 1997" "LINUX MANPAGE" "Bibliotheksfunktionen"
.SH BEZEICHNUNG
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- Eingabeformatierung
.SH ÜBERSICHT
.nf
.B #include <stdio.h>
.na
.BI "int scanf( const char *" format ", ..." );
.br
.BI "int fscanf( FILE *" stream ", const char *" format ", ..." );
.br
.BI "int sscanf( const char *" str ", const char *" format ", ..." );
.sp
.B #include <stdarg.h>
.BI "int vscanf( const char *" format ", va_list " ap );
.br
.BI "int vsscanf( const char *" str ", const char *" format ", va_list " ap );
.br
.BI "int vfscanf( FILE *" stream ", const char *" format ", va_list " ap );
.ad
.SH BESCHREIBUNG
Die Funktionenfamilie
.B scanf
prüft Eingaben in Bezug auf ein
.I format
wie unten beschrieben.  Dieses Format darf
.IR "Umwandlungsspezifikationen"
enthalten; die Ergebnisse solcher Umwandlungen, falls vorhanden, werden durch
die
.I pointer
-Argumente gespeichert.  Die Funktion
.B scanf
liest Eingaben vom Standardeingabekanal
.IR stdin ,
.B fscanf
liest Eingaben von dem Streamzeiger
.IR stream ,
und
.B sscanf
liest ihre Eingaben von dem String, auf den
.IR str
zeigt.
.PP
Die Funktion
.B vfscanf
verhält sich analog zu
.BR vfprintf (3)
und liest Eingaben von dem Streamzeiger
.I stream ,
wobei eine variable Argumentliste von Zeigern benutzt wird (siehe
.BR stdarg (3).
Die Funktion
.B vscanf
liest eine variable Argumentliste von der Standardeingabe und die Funktion
.B vsscanf
liest von einem String; diese sind analog zu den Funktionen
.B vprintf
und
.B vsprintf .
.PP
Jedes folgende Argument
.I pointer
muss genau zu jedem folgenden Umwandlungsspezifakator passen
(siehe `unterdrücken' unten).  Jede Umwandlung wird durch das Zeichen
.B %
(Prozentzeichen) eingeleitet.  Der String
.I format
darf auch andere Zeichen enthalten.  Leerräume (wie Leerzeichen,
Tabulatoren oder Zeilenumbrüche) im String
.I format
passen zu einem Freiraum jeder Größe, eingeschlossen keinem Freiraum,
der Eingabe.
Alles andere passt nur zu sich selbst.  Einlesen der Daten stoppt, wenn
ein Eingabezeichen nicht zu einem Formatzeichen passt.  Einlesen stoppt auch,
wenn die Umwandlung nicht durchgeführt werden kann (siehe unten).
.SH Umwandlungen
Dem Zeichen
.B % ,
welches eine Umwandlung einleitet, dürfen einige
.I flag
-Zeichen folgen:
.TP
.B *
Unterdrückt Zuordnung.  Die folgende Umwandlung wird wie gewohnt durchgeführt,
jedoch wird keine Zeiger benutzt; das Ergebnis der Umwandlung wird verworfen.
.TP
.B a 
Zeigt an, dass die Umwandlung
.BR s
sein wird; der nötige Speicher für den String wird malloc't,  und
der Zeiger darauf wird der Zeigervariablen
.I  char
zugeordnet, welche nicht initialisiert zu werden braucht.
Dieses Flag existiert nicht in
.IR "ANSI C" .
.TP
.B h
Zeigt an, dass die Umwandlung eine von
.B dioux
oder
.B n
sein wird, und der nächste Zeiger ein Zeiger auf ein
.I short  int
(im Gegensatz zu
.IR int 
) sein wird.
.TP
.B l
Zeigt an, dass die Umwandlung eine von
.B dioux
oder
.B n
sein wird, und der nächste Zeiger ein Zeiger auf ein
.I long  int
(im Gegensatz zu
.IR int
) sein wird,
oder dass die Umwandlung eine von
.B efg
sein wird, und der nächste Zeiger ein Zeiger auf ein
.I double
(im Gegensatz zu
.IR float
) sein wird.
Angabe von zwei Flags
.B l
in äquivalent zum Flag
.B L.
.TP
.B L
Zeigt an, dass die Umwandlung eine von
.B efg
sein wird und der nächste Zeiger ein Zeiger auf ein
.IR "long double" 
ist, oder dass die Umwandlung eine von
.B dioux
sein wird und der nächste Zeiger ein Zeiger auf ein
.IR "long long"
sein wird.
(Beachte, dass "long long" kein Typ nach
.I ANSI C 
ist.  Jedes Programm, das dies benutzt wird nicht auf alle anderen
Architekturen übertragbar sein.)
.TP
.B q
ist äquivalent zu L. 
Dieses Flag existiert nicht in
.IR "ANSI C" .
.PP
Zusätzlich zu diesen Flags darf es eine optionale maximale Feldgröße geben,
die als dezimale Ganzzahl zwischen dem
.B %
und der Umwandlung angegeben wird.  Wenn keine Größe angegeben ist wird per
Vorgabe `unendlich' benutzt (mit einer Ausnahme, siehe unten); anderenfalls
werden höchstens diese Anzahl von Zeichen durch die Umwandlung verarbeitet.
Bevor die Umwandlung beginnt übergehen die meisten Umwandlungen Leerräume;
diese Leerräume zählen nicht gegenüber der Feldgröße.
.PP
Die folgenden Umwandlungen sind verfügbar:
.TP
.B %
Findet ein Zeichen `%'.  Das heißt, `%\&%' im Formatstring findet ein
einzelnes Zeichnen `%'.  Es findet keine Umwandlung statt und Zuweisung
tritt nicht auf.
.TP
.B d
Findet eine optional verzeichenbehaftete dezimale Ganzzahl;
der nächste Zeiger muss ein Zeiger auf
.IR int
sein.
.TP
.B D
Äquivalent zu
.BR ld ;
dies existiert nur aus Kompatibilitätsgründen.
.TP
.B i
Findet eine optional verzeichenbehaftete Ganzzahl; der nächste Zeiger muss
ein Zeiger auf
.IR int
sein.
Die Ganzzahl wird eingelesen zur Basis 16 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.
.TP
.B o
Findet eine vorzeichenfreie oktale Ganzzahl; der nächste Zeiger muss ein Zeiger
auf ein
.IR "unsigned int"
sein.
.TP
.B u
Findet eine vorzeichenfreie dezimale Ganzzahl; der nächste Zeiger muss ein
Zeiger auf ein
.IR "unsigned int"
sein.
.TP
.B x
Findet eine vorzeichenfreie hexadezimale Ganzzahl; der nächste Zeiger muss ein
Zeiger auf ein
.IR "unsigned int"
sein.
.TP
.B X
Äquivalent zu
.B x 
.TP
.B f
Findet eine optional vorzeichenbehaftete Fließkommazahl; der nächste Zeiger muss ein
Zeiger auf ein
.IR float
sein.
.TP
.B e
Äquivalent zu
.BR f .
.TP
.B g
Äquivalent zu
.BR f .
.TP
.B E
Äquivalent zu
.BR f 
.TP
.B s
Findet eine Folge von Zeichen, die keinen Leerraum darstellen; der nächste
Zeiger muss Zeiger auf
.IR char
sein, und das Feld muss groß genug sein um die Folge und das abschließende
.B NUL
Zeichen aufzunehmen.  Der Eingabestring stoppt an Leerräumen oder an der
maximalen Feldgrößen, je nachdem, was zuerst auftritt.
.TP
.B c
Findet eine Folge von
.I width
Zeichen (Vorgabe 1); der nächste Zeiger muss Zeiger auf
.IR char
sein und es muss genug Platz für alle Zeichen existieren. (Es wird kein
abschließendes
.B NUL
angehängt.)  Das gewöhnliche Unterdrücken vor einleitenden Leerräumen
wird unterdrückt.  Um Leerräume zu überspringen benutze explizit ein
Leerzeichen im Formatstring.
.TP
.B \&[
Findet eine nichtleere Folge von Zeichen aus der angegebenen Menge von zu
akzeptierenden Zeichen; der nächste Zeiger muss Zeiger auf
.IR char
sein und es muss genug Platz für alle Zeichen des Strings sein, plus
einem abschließenden
.B NUL
Zeichen.  Das gewöhnliche Unterdrücken vor einleitenden Leerräumen
wird unterdrückt.  Der Strings soll aus Zeichen zusammengesetzt werden, die
(nicht) in einer bestimmten Menge sind; die Menge wird definiert durch die
Zeichen einer öffnenden
.B [
und einer schließenden
.B ]
Klammen.  Die Menge
.I schließt diese Zeichen aus
wenn das erste Zeichen nach der öffnenden Klammer ein circumflex
.BR ^
ist.
Im einer schließende Klammer in der Menge zu haben, gib sie als erstes
Zeichen hinter der öffnenden Klammer oder dem circumflex an; jede andere
Position beendet die Menge.
Der Bindestrich
.B -
ist auch ein spezielles Zeichen; wenn er zwischen zwei anderen Zeichen
steht fügt er alle Zeichen zwischen den beiden zu der Menge hinzu.
Um einen Bindestrich zuzufügen, gib ihn als letztes Zeichen vor der
schließenden Klammer an.  Zum Beispiel meint `[^]0-9-]' `alles außer
schließender Klammen, Null bis Neun, und Bindestrich'
Der String endet bei Auftreten eines Zeichens, das sich nicht in der Menge
befindet (oder bei circumflex bei Auftreten eines Zeichens, das sich in der
Menge befindet), oder bei Erreichen der Feldgröße.
.TP
.B p
Findet einen Zeigerwert (wie durch `%p' ausgegeben bei
.BR printf (3);
der nächste Zeiger muss ein Zeiger auf
.IR void
sein.
.TP
.B n
Nichts wird erwartet; stattdessen wird die Anzahl der Zeichen, die bis jetzt
eingelesen wurden, im nächsten Zeiger gespeichert, welcher ein Zeiger auf
.IR int
sein muss.
Dies ist
.I keine
Umwandlung, obwohl sie durch das Flag
.B *
unterdrückt werden kann.
.PP
.SH "RÜCKGABEWERTE"
Diese Funktionen geben die Anzahl der zugewiesenen Eingabeelemente zurück,
welche kleiner als gewünscht sein kann, oder auch Null im Fall einer
fehlgeschlagenen Suche.
Null zeigt an, dass obwohl Eingabe verfügbar war, keine Zuweisung erfolgt
ist; typischerweise durch ungültige Eingabezeichen, wie ein alphabetisches
Zeichen für eine Umwandlung %d'.  Der Wert
.B EOF
wird zurückgegeben wenn ein Eingabefehler vor einer Umwandlung auftritt,
wie z.B. ein Dateiende.  Wenn ein Fehler oder Dateiende auftritt, nachdem
eine Umwandlung begonnen hat, wird die Anzahl der bis dahin erfolgreich
umgewandelten Zeichen zurückgegeben.
.SH "SIEHE AUCH"
.BR strtol (3),
.BR strtoul (3),
.BR strtod (3),
.BR getc (3),
.BR printf (3).
.SH STANDARDS
Die Funktionen
.BR fscanf ,
.BR scanf ,
und
.BR sscanf
sind konform zu ANSI C3.159-1989 (``ANSI C'').
.PP
Das Flag
.B q
ist in
.I BSD 4.4
die Notation für
.IR "long long" ,
während
.B ll
oder die Benutzung von
.B L
in Ganzzahlumwandlungen die GNU-Notation ist.
.PP
Die Linuxversion dieser Funktionen basiert auf der
.I GNU 
.I libio
Bibliothek.  Eine konkretere Beschreibung findet sich in der
.I info
-Dokumentation von
.I GNU
.I libc (glibc-1.08).
.SH BUGS 
Alle Funktionen sind vollkommen konform zu ANSI C3.159-1989, stellen jedoch
die zusätzliche Flags
.B q
und
.B a
, sowie ein zusätzliches Verhalten der Flags
.B L
und 
.B l 
zur Verfügung.  Letzteres kann als Bug angesehen werden, da es das Verhalten
der Flags verändert, die in ANSI C3.159-1989 definiert sind.
.PP
Einige Kombinationen von Flags, die durch
.I ANSI C
definiert sind, machen in
.IR "ANSI C"
keinen Sinn (e.g. 
.BR "%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 Flags zu benutzen, die gar nicht durch
.I ANSI C
definiert sind, d.h. benutze
.B q
anstatt
.B L
in Kombination mit Umwandlungen
.B diouxX
oder
.BR ll .
.PP
Die Benutzung von
.B q
ist nicht die gleiche wie bei
.IR "BSD 4.4" ,
da die in Fließkommaumwandlungen äquivalent zu
.BR L
benutzt werden kann.