BEZEICHNUNG¶

Ü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():

BESCHREIBUNG¶

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 Maskierungszeichen (') für dezimale Umwandlungen. Dies legt fest, 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.

•

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.

•

ein 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.

RÜCKGABEWERT¶

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 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¶

KONFORM ZU¶

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¶

FEHLER¶

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.

BEISPIEL¶

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¶

KOLOPHON¶

ÜBERSETZUNG¶

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>.