git.infodrom.org Git - infodrom/manpages-de/blob - man3/scanf.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)scanf.3     6.14 (Berkeley) 1/8/93
  37 .\"
  38 .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
  39 .\" modified to resemble the GNU libio setup used in the Linux libc
  40 .\" used in versions 4.x (x>4) and 5   Helmut.Geyer@iwr.uni-heidelberg.de
  41 .\"
  42 .\" Translated to German Sun Feb 23 1997 by Patrick Rother <krd@gulu.net>
  43 .\"
  44 .TH SCANF 3  "3. Januar 1997" "LINUX MANPAGE" "Bibliotheksfunktionen"
  45 .SH BEZEICHNUNG
  46 scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- Eingabeformatierung
  47 .SH ÜBERSICHT
  48 .nf
  49 .B #include <stdio.h>
  50 .na
  51 .BI "int scanf( const char *" format ", ..." );
  52 .br
  53 .BI "int fscanf( FILE *" stream ", const char *" format ", ..." );
  54 .br
  55 .BI "int sscanf( const char *" str ", const char *" format ", ..." );
  56 .sp
  57 .B #include <stdarg.h>
  58 .BI "int vscanf( const char *" format ", va_list " ap );
  59 .br
  60 .BI "int vsscanf( const char *" str ", const char *" format ", va_list " ap );
  61 .br
  62 .BI "int vfscanf( FILE *" stream ", const char *" format ", va_list " ap );
  63 .ad
  64 .SH BESCHREIBUNG
  65 Die Funktionenfamilie
  66 .B scanf
  67 prüft Eingaben in Bezug auf ein
  68 .I format
  69 wie unten beschrieben.  Dieses Format darf
  70 .IR "Umwandlungsspezifikationen"
  71 enthalten; die Ergebnisse solcher Umwandlungen, falls vorhanden, werden durch
  72 die
  73 .I pointer
  74 -Argumente gespeichert.  Die Funktion
  75 .B scanf
  76 liest Eingaben vom Standardeingabekanal
  77 .IR stdin ,
  78 .B fscanf
  79 liest Eingaben von dem Streamzeiger
  80 .IR stream ,
  81 und
  82 .B sscanf
  83 liest ihre Eingaben von dem String, auf den
  84 .IR str
  85 zeigt.
  86 .PP
  87 Die Funktion
  88 .B vfscanf
  89 verhält sich analog zu
  90 .BR vfprintf (3)
  91 und liest Eingaben von dem Streamzeiger
  92 .I stream ,
  93 wobei eine variable Argumentliste von Zeigern benutzt wird (siehe
  94 .BR stdarg (3).
  95 Die Funktion
  96 .B vscanf
  97 liest eine variable Argumentliste von der Standardeingabe und die Funktion
  98 .B vsscanf
  99 liest von einem String; diese sind analog zu den Funktionen
 100 .B vprintf
 101 und
 102 .B vsprintf .
 103 .PP
 104 Jedes folgende Argument
 105 .I pointer
 106 muss genau zu jedem folgenden Umwandlungsspezifakator passen
 107 (siehe `unterdrücken' unten).  Jede Umwandlung wird durch das Zeichen
 108 .B %
 109 (Prozentzeichen) eingeleitet.  Der String
 110 .I format
 111 darf auch andere Zeichen enthalten.  Leerräume (wie Leerzeichen,
 112 Tabulatoren oder Zeilenumbrüche) im String
 113 .I format
 114 passen zu einem Freiraum jeder Größe, eingeschlossen keinem Freiraum,
 115 der Eingabe.
 116 Alles andere passt nur zu sich selbst.  Einlesen der Daten stoppt, wenn
 117 ein Eingabezeichen nicht zu einem Formatzeichen passt.  Einlesen stoppt auch,
 118 wenn die Umwandlung nicht durchgeführt werden kann (siehe unten).
 119 .SH Umwandlungen
 120 Dem Zeichen
 121 .B % ,
 122 welches eine Umwandlung einleitet, dürfen einige
 123 .I flag
 124 -Zeichen folgen:
 125 .TP
 126 .B *
 127 Unterdrückt Zuordnung.  Die folgende Umwandlung wird wie gewohnt durchgeführt,
 128 jedoch wird keine Zeiger benutzt; das Ergebnis der Umwandlung wird verworfen.
 129 .TP
 130 .B a
 131 Zeigt an, dass die Umwandlung
 132 .BR s
 133 sein wird; der nötige Speicher für den String wird malloc't,  und
 134 der Zeiger darauf wird der Zeigervariablen
 135 .I  char
 136 zugeordnet, welche nicht initialisiert zu werden braucht.
 137 Dieses Flag existiert nicht in
 138 .IR "ANSI C" .
 139 .TP
 140 .B h
 141 Zeigt an, dass die Umwandlung eine von
 142 .B dioux
 143 oder
 144 .B n
 145 sein wird, und der nächste Zeiger ein Zeiger auf ein
 146 .I short  int
 147 (im Gegensatz zu
 148 .IR int
 149 ) sein wird.
 150 .TP
 151 .B l
 152 Zeigt an, dass die Umwandlung eine von
 153 .B dioux
 154 oder
 155 .B n
 156 sein wird, und der nächste Zeiger ein Zeiger auf ein
 157 .I long  int
 158 (im Gegensatz zu
 159 .IR int
 160 ) sein wird,
 161 oder dass die Umwandlung eine von
 162 .B efg
 163 sein wird, und der nächste Zeiger ein Zeiger auf ein
 164 .I double
 165 (im Gegensatz zu
 166 .IR float
 167 ) sein wird.
 168 Angabe von zwei Flags
 169 .B l
 170 in äquivalent zum Flag
 171 .B L.
 172 .TP
 173 .B L
 174 Zeigt an, dass die Umwandlung eine von
 175 .B efg
 176 sein wird und der nächste Zeiger ein Zeiger auf ein
 177 .IR "long double"
 178 ist, oder dass die Umwandlung eine von
 179 .B dioux
 180 sein wird und der nächste Zeiger ein Zeiger auf ein
 181 .IR "long long"
 182 sein wird.
 183 (Beachte, dass "long long" kein Typ nach
 184 .I ANSI C
 185 ist.  Jedes Programm, das dies benutzt wird nicht auf alle anderen
 186 Architekturen übertragbar sein.)
 187 .TP
 188 .B q
 189 ist äquivalent zu L.
 190 Dieses Flag existiert nicht in
 191 .IR "ANSI C" .
 192 .PP
 193 Zusätzlich zu diesen Flags darf es eine optionale maximale Feldgröße geben,
 194 die als dezimale Ganzzahl zwischen dem
 195 .B %
 196 und der Umwandlung angegeben wird.  Wenn keine Größe angegeben ist wird per
 197 Vorgabe `unendlich' benutzt (mit einer Ausnahme, siehe unten); anderenfalls
 198 werden höchstens diese Anzahl von Zeichen durch die Umwandlung verarbeitet.
 199 Bevor die Umwandlung beginnt übergehen die meisten Umwandlungen Leerräume;
 200 diese Leerräume zählen nicht gegenüber der Feldgröße.
 201 .PP
 202 Die folgenden Umwandlungen sind verfügbar:
 203 .TP
 204 .B %
 205 Findet ein Zeichen `%'.  Das heißt, `%\&%' im Formatstring findet ein
 206 einzelnes Zeichnen `%'.  Es findet keine Umwandlung statt und Zuweisung
 207 tritt nicht auf.
 208 .TP
 209 .B d
 210 Findet eine optional verzeichenbehaftete dezimale Ganzzahl;
 211 der nächste Zeiger muss ein Zeiger auf
 212 .IR int
 213 sein.
 214 .TP
 215 .B D
 216 Äquivalent zu
 217 .BR ld ;
 218 dies existiert nur aus Kompatibilitätsgründen.
 219 .TP
 220 .B i
 221 Findet eine optional verzeichenbehaftete Ganzzahl; der nächste Zeiger muss
 222 ein Zeiger auf
 223 .IR int
 224 sein.
 225 Die Ganzzahl wird eingelesen zur Basis 16 wenn sie mit `0x' oder `0X' beginnt,
 226 zur Basis 8 wenn sie mit `0' beginnt, anderenfalls zur Basis 10.  Nur Zeichen,
 227 die zur Basis passen, werden benutzt.
 228 .TP
 229 .B o
 230 Findet eine vorzeichenfreie oktale Ganzzahl; der nächste Zeiger muss ein Zeiger
 231 auf ein
 232 .IR "unsigned int"
 233 sein.
 234 .TP
 235 .B u
 236 Findet eine vorzeichenfreie dezimale Ganzzahl; der nächste Zeiger muss ein
 237 Zeiger auf ein
 238 .IR "unsigned int"
 239 sein.
 240 .TP
 241 .B x
 242 Findet eine vorzeichenfreie hexadezimale Ganzzahl; der nächste Zeiger muss ein
 243 Zeiger auf ein
 244 .IR "unsigned int"
 245 sein.
 246 .TP
 247 .B X
 248 Äquivalent zu
 249 .B x
 250 .TP
 251 .B f
 252 Findet eine optional vorzeichenbehaftete Fließkommazahl; der nächste Zeiger muss ein
 253 Zeiger auf ein
 254 .IR float
 255 sein.
 256 .TP
 257 .B e
 258 Äquivalent zu
 259 .BR f .
 260 .TP
 261 .B g
 262 Äquivalent zu
 263 .BR f .
 264 .TP
 265 .B E
 266 Äquivalent zu
 267 .BR f
 268 .TP
 269 .B s
 270 Findet eine Folge von Zeichen, die keinen Leerraum darstellen; der nächste
 271 Zeiger muss Zeiger auf
 272 .IR char
 273 sein, und das Feld muss groß genug sein um die Folge und das abschließende
 274 .B NUL
 275 Zeichen aufzunehmen.  Der Eingabestring stoppt an Leerräumen oder an der
 276 maximalen Feldgrößen, je nachdem, was zuerst auftritt.
 277 .TP
 278 .B c
 279 Findet eine Folge von
 280 .I width
 281 Zeichen (Vorgabe 1); der nächste Zeiger muss Zeiger auf
 282 .IR char
 283 sein und es muss genug Platz für alle Zeichen existieren. (Es wird kein
 284 abschließendes
 285 .B NUL
 286 angehängt.)  Das gewöhnliche Unterdrücken vor einleitenden Leerräumen
 287 wird unterdrückt.  Um Leerräume zu überspringen benutze explizit ein
 288 Leerzeichen im Formatstring.
 289 .TP
 290 .B \&[
 291 Findet eine nichtleere Folge von Zeichen aus der angegebenen Menge von zu
 292 akzeptierenden Zeichen; der nächste Zeiger muss Zeiger auf
 293 .IR char
 294 sein und es muss genug Platz für alle Zeichen des Strings sein, plus
 295 einem abschließenden
 296 .B NUL
 297 Zeichen.  Das gewöhnliche Unterdrücken vor einleitenden Leerräumen
 298 wird unterdrückt.  Der Strings soll aus Zeichen zusammengesetzt werden, die
 299 (nicht) in einer bestimmten Menge sind; die Menge wird definiert durch die
 300 Zeichen einer öffnenden
 301 .B [
 302 und einer schließenden
 303 .B ]
 304 Klammen.  Die Menge
 305 .I schließt diese Zeichen aus
 306 wenn das erste Zeichen nach der öffnenden Klammer ein circumflex
 307 .BR ^
 308 ist.
 309 Im einer schließende Klammer in der Menge zu haben, gib sie als erstes
 310 Zeichen hinter der öffnenden Klammer oder dem circumflex an; jede andere
 311 Position beendet die Menge.
 312 Der Bindestrich
 313 .B -
 314 ist auch ein spezielles Zeichen; wenn er zwischen zwei anderen Zeichen
 315 steht fügt er alle Zeichen zwischen den beiden zu der Menge hinzu.
 316 Um einen Bindestrich zuzufügen, gib ihn als letztes Zeichen vor der
 317 schließenden Klammer an.  Zum Beispiel meint `[^]0-9-]' `alles außer
 318 schließender Klammen, Null bis Neun, und Bindestrich'
 319 Der String endet bei Auftreten eines Zeichens, das sich nicht in der Menge
 320 befindet (oder bei circumflex bei Auftreten eines Zeichens, das sich in der
 321 Menge befindet), oder bei Erreichen der Feldgröße.
 322 .TP
 323 .B p
 324 Findet einen Zeigerwert (wie durch `%p' ausgegeben bei
 325 .BR printf (3);
 326 der nächste Zeiger muss ein Zeiger auf
 327 .IR void
 328 sein.
 329 .TP
 330 .B n
 331 Nichts wird erwartet; stattdessen wird die Anzahl der Zeichen, die bis jetzt
 332 eingelesen wurden, im nächsten Zeiger gespeichert, welcher ein Zeiger auf
 333 .IR int
 334 sein muss.
 335 Dies ist
 336 .I keine
 337 Umwandlung, obwohl sie durch das Flag
 338 .B *
 339 unterdrückt werden kann.
 340 .PP
 341 .SH "RÜCKGABEWERTE"
 342 Diese Funktionen geben die Anzahl der zugewiesenen Eingabeelemente zurück,
 343 welche kleiner als gewünscht sein kann, oder auch Null im Fall einer
 344 fehlgeschlagenen Suche.
 345 Null zeigt an, dass obwohl Eingabe verfügbar war, keine Zuweisung erfolgt
 346 ist; typischerweise durch ungültige Eingabezeichen, wie ein alphabetisches
 347 Zeichen für eine Umwandlung %d'.  Der Wert
 348 .B EOF
 349 wird zurückgegeben wenn ein Eingabefehler vor einer Umwandlung auftritt,
 350 wie z.B. ein Dateiende.  Wenn ein Fehler oder Dateiende auftritt, nachdem
 351 eine Umwandlung begonnen hat, wird die Anzahl der bis dahin erfolgreich
 352 umgewandelten Zeichen zurückgegeben.
 353 .SH "SIEHE AUCH"
 354 .BR strtol (3),
 355 .BR strtoul (3),
 356 .BR strtod (3),
 357 .BR getc (3),
 358 .BR printf (3).
 359 .SH STANDARDS
 360 Die Funktionen
 361 .BR fscanf ,
 362 .BR scanf ,
 363 und
 364 .BR sscanf
 365 sind konform zu ANSI C3.159-1989 (``ANSI C'').
 366 .PP
 367 Das Flag
 368 .B q
 369 ist in
 370 .I BSD 4.4
 371 die Notation für
 372 .IR "long long" ,
 373 während
 374 .B ll
 375 oder die Benutzung von
 376 .B L
 377 in Ganzzahlumwandlungen die GNU-Notation ist.
 378 .PP
 379 Die Linuxversion dieser Funktionen basiert auf der
 380 .I GNU
 381 .I libio
 382 Bibliothek.  Eine konkretere Beschreibung findet sich in der
 383 .I info
 384 -Dokumentation von
 385 .I GNU
 386 .I libc (glibc-1.08).
 387 .SH BUGS
 388 Alle Funktionen sind vollkommen konform zu ANSI C3.159-1989, stellen jedoch
 389 die zusätzliche Flags
 390 .B q
 391 und
 392 .B a
 393 , sowie ein zusätzliches Verhalten der Flags
 394 .B L
 395 und
 396 .B l
 397 zur Verfügung.  Letzteres kann als Bug angesehen werden, da es das Verhalten
 398 der Flags verändert, die in ANSI C3.159-1989 definiert sind.
 399 .PP
 400 Einige Kombinationen von Flags, die durch
 401 .I ANSI C
 402 definiert sind, machen in
 403 .IR "ANSI C"
 404 keinen Sinn (e.g.
 405 .BR "%Ld" ).
 406 Während sie ein wohldefiniertes Verhalten unter Linux haben, braucht dies
 407 auf anderen Architekturen nicht der Fall zu sein. Daher ist es gewöhnlich
 408 besser Flags zu benutzen, die gar nicht durch
 409 .I ANSI C
 410 definiert sind, d.h. benutze
 411 .B q
 412 anstatt
 413 .B L
 414 in Kombination mit Umwandlungen
 415 .B diouxX
 416 oder
 417 .BR ll .
 418 .PP
 419 Die Benutzung von
 420 .B q
 421 ist nicht die gleiche wie bei
 422 .IR "BSD 4.4" ,
 423 da die in Fließkommaumwandlungen äquivalent zu
 424 .BR L
 425 benutzt werden kann.