.\" 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
prft Eingaben in Bezug auf ein
.I format
wie unten beschrieben.  Dieses Format darf
.IR "Umwandlungsspezifikationen"
enthalten; die Ergebnisse solcher Umwandungen, 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
verhlt 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
mu genau zu jedem folgenden Umwandlungsspezifakator passen
(siehe `unterdrcken' unten).  Jede Umwandlung wird durch das Zeichen
.B %
(Prozentzeichen) eingeleitet.  Der String
.I format
darf auch andere Zeichen enthalten.  Leerrume (wie Leerzeichen,
Tabulatoren oder Zeilenumbrche) im String
.I format
passen zu einem Freiraum jeder Gre, 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 durchgefhrt werden kann (siehe unten).
.SH Umwandlungen
Dem Zeichen
.B % ,
welches eine Umwandlung einleitet, drfen einige
.I flag
-Zeichen folgen:
.TP
.B *
Unterdrckt Zuordnung.  Die folgende Umwandlung wird wie gewohnt durchgefhrt,
jedoch wird keine Zeiger benutzt; das Ergebnis der Umwandlung wird verworfen.
.TP
.B a 
Zeigt an, da die Umwandlung
.BR s
sein wird; der ntige Speicher fr 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, da die Umwandlung eine von
.B dioux
oder
.B n
sein wird, und der nchste Zeiger ein Zeiger auf ein
.I short  int
(im Gegensatz zu
.IR int 
) sein wird.
.TP
.B l
Zeigt an, da die Umwandlung eine von
.B dioux
oder
.B n
sein wird, und der nchste Zeiger ein Zeiger auf ein
.I long  int
(im Gegensatz zu
.IR int
) sein wird,
oder da die Umwandlung eine von
.B efg
sein wird, und der nchste 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, da die Umwandlung eine von
.B efg
sein wird und der nchste Zeiger ein Zeiger auf ein
.IR "long double" 
ist, oder da die Umwandlung eine von
.B dioux
sein wird und der nchste Zeiger ein Zeiger auf ein
.IR "long long"
sein wird.
(Beachte, da "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 quvalent zu L. 
Dieses Flag existiert nicht in
.IR "ANSI C" .
.PP
Zustzlich zu diesen Flags darf es eine optionale maximale Feldgre geben,
die als dezimale Ganzzahl zwischen dem
.B %
und der Umwandlung angegeben wird.  Wenn keine Gre angegeben ist wird per
Vorgabe `unendlich' benutzt (mit einer Ausnahme, siehe unten); anderenfalls
werden hchstens diese Anzahl von Zeichen durch die Umwandlung verarbeitet.
Bevor die Umwandlung beginnt bergehen die meisten Umwandungen Leerrume;
diese Leerrume zhlen nicht gegenber der Feldgre.
.PP
Die folgenden Umwandlungen sind verfgbar:
.TP
.B %
Findet ein Zeichen `%'.  Das heisst, `%\&%' 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 nchste Zeiger mu ein Zeiger auf
.IR int
sein.
.TP
.B D
quivalent zu
.BR ld ;
dies existiert nur aus Kompatibilittsgrnden.
.TP
.B i
Findet eine optional verzeichenbehaftete Ganzzahl; der nchste Zeiger mu
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 nchste Zeiger mu ein Zeiger
auf ein
.IR "unsigned int"
sein.
.TP
.B u
Findet eine vorzeichenfreie dezimale Ganzzahl; der nchste Zeiger mu ein
Zeiger auf ein
.IR "unsigned int"
sein.
.TP
.B x
Findet eine vorzeichenfreie hexadezimale Ganzzahl; der nchste Zeiger mu ein
Zeiger auf ein
.IR "unsigned int"
sein.
.TP
.B X
quivalent zu
.B x 
.TP
.B f
Findet eine optional vorzeichenbehaftete Fliekommazahl; der nchste Zeiger mu 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 nchste
Zeiger mu Zeiger auf
.IR char
sein, und das Feld mu gro genug sein um die Folge und das abschlieende
.B NUL
Zeichen aufzunehmen.  Der Eingabestring stoppt an Leerrumen oder an der
maximalen Feldgren, je nachdem, was zuerst auftritt.
.TP
.B c
Findet eine Folge von
.I width
Zeichen (Vorgabe 1); der nchste Zeiger mu Zeiger auf
.IR char
sein und es mu genug Platz fr alle Zeichen existieren. (Es wird kein
abschlieendes
.B NUL
angehngt.)  Das gewhnliche Unterdrcken vor einleitenden Leerrumen
wird unterdrckt.  Um Leerrume 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 nchste Zeiger mu Zeiger auf
.IR char
sein und es muss genug Platz fr alle Zeichen des Strings sein, plus
einem abschlieenden
.B NUL
Zeichen.  Das gewhnliche Unterdrcken vor einleitenden Leerrumen
wird unterdrckt.  Der Strings soll aus Zeichen zusammengesetzt werden, die
(nicht) in einer bestimmten Menge sind; die Menge wird definniert durch die
Zeichen einer ffnenden
.B [
und einer schlieenden
.B ]
Klammen.  Die Menge
.I schliet diese Zeichen aus
wenn das erste Zeichen nach der ffnenden Klammer ein circumflex
.BR ^
ist.
Im einer schlieende 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 fgt er alle Zeichen zwischen den beiden zu der Menge hinzu.
Um einen Bindestrich zuzufgen, gib ihn als letztes Zeichen vor der
schlieenden Klammer an.  Zum Beispiel meint `[^]0-9-]' `alles auer
schlieender Klammen, Null bis Neun, und Bindestrich'
Der String endet bei Auftreten eines Zeichens, da sich nicht in der Menge
befindet (oder bei circumflex bei Auftreten eines Zeichens, da sich in der
Menge befindet), oder bei Erreichen der Feldgre.
.TP
.B p
Findet einen Zeigerwert (wie durch `%p' ausgegeben bei
.BR printf (3);
der nchste Zeiger mu ein Zeiger auf
.IR void
sein.
.TP
.B n
Nichts wird erwartet; stattdessen wird die Anzahl der Zeichen, die bis jetzt
eingelesen wurden, im nchsten Zeiger gespeichert, welcher ein Zeiger auf
.IR int
sein mu.
Dies ist
.I keine
Umwandlung, obwohl sie durch das Flag
.B *
unterdrckt werden kann.
.PP
.SH "RCKGABEWERTE"
Diese Funktionen geben die Anzahl der zugewiesenen Eingabeelemente zurck,
welche kleiner als gewnscht sein kann, oder auch Null im Fall einer
fehlgeschlagenen Suche.
Null zeigt an, dass obwohl Eingabe verfgbar war, keine Zuweisung erfolgt
ist; typischerweise durch ungltige Eingabezeichen, wie ein alphabetisches
Zeichen fr eine Umwandlung %d'.  Der Wert
.B EOF
wird zurckgegeben 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 zurckgegeben.
.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 fr
.IR "long long" ,
whrend
.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 zustzliche Flags
.B q
und
.B a
, sowie ein zustzliches Verhalten der Flags
.B L
und 
.B l 
zur Verfgung.  Letzteres kann als Bug angesehen werden, da es das Verhalten
der Flags verndert, 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" ).
Whrend sie ein wohldefiniertes Verhalten unter Linux haben, braucht dies
auf anderen Architekturen nicht der Fall zu sein. Daher ist es gewhnlich
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 Fliekommaumwandlungen quivalent zu
.BR L
benutzt werden kann.