Provided by: manpages-de-dev_4.27.0-1_all 
BEZEICHNUNG
sscanf, vsscanf - Formatumwandlungen von Eingabezeichenketten
BIBLIOTHEK
Standard-C-Bibliothek (libc, -lc)
ÜBERSICHT
#include <stdio.h>
int sscanf(const char *restrict zeichenkette,
const char *restrict format, …);
#include <stdarg.h>
int vsscanf(const char *restrict zeichenkette,
const char *restrict format, va_list ap);
Mit Glibc erforderliche Feature-Test-Makros (siehe feature_test_macros(7)):
vsscanf():
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
BESCHREIBUNG
Die Funktionenfamilie sscanf() untersucht formatierte Eingabe entsprechend 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 format halten. Jedes Zeiger-Argument muss einen geeigneten Typ für den Rückgabewert der
zugehörigen Umwandlungsspezifikation haben.
Falls die Anzahl der Umwandlungsspezifikationen in format die Anzahl der Zeiger-Argumente übersteigt,
sind die Ergebnisse undefiniert. Falls die Anzahl der Zeiger-Argumente die Anzahl der
Umwandlungsspezifikationen übersteigt, werden die überzähligen Zeiger-Argumente ausgewertet, aber
ansonsten ignoriert.
sscanf() Diese Funktionen lesen ihre Eingabe aus der Zeichenkette, auf die zeichenkette zeigt.
Die Funktion vsscanf() verhält sich analog zu 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 sscanf() 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 keinem, 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: sscanf() 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 sscanf() 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
abschließendes Nullbyte (»\0«), um das Ende der Eingabe zu kennzeichnen; die maximale Feldbreite
enthält dieses Endezeichen nicht.
• Ein optionales Typveränderungszeichen. Beispielsweise wird der Typveränderer l mit
Ganzzahlumwandlungen wie %d verwandt, um festzulegen, dass sich das entsprechende Zeiger-Argument
auf ein long anstelle eines Zeigers auf ein int bezieht.
• Ein Umwandlungskennzeichner, der die Art der durchzuführende Eingabeumwandlung festlegt.
Die Umwandlungskennzeichner in format gibt es in zwei Formen, entweder mit »%« oder mit »%n$« am Anfang.
Die zwei Formen sollten in der gleichen format-Zeichenkette nicht gemischt werden, außer dass eine
Zeichenkette, die »%n$«-Angaben enthält %% und %* enthalten kann. Falls format »%«-Angaben enthält, dann
entsprechen sie in der Reihenfolge nachfolgenden Zeiger-Argumenten. In der Form »%n$« (die in
POSIX.1-2001, aber nicht in C99 festgelegt ist) ist n eine dezimale Ganzzahl, die festlegt, dass
umgewandelte Eingabe an dem Ort abgelegt werden soll, auf den sich das n-1 Zeiger-Argument bezieht, das
format folgt.
Umwandlungen
Die folgenden Typveränderungszeichen können in einer Umwandlungsfestlegung auftauchen:
h Zeigt an, dass die Umwandlung eine aus d, i, o, u, x, X, n sein wird und dass der nächste Zeiger
ein Zeiger auf short oder unsigned short (anstelle von int) ist.
hh Wie bei h, aber der nächste Zeiger ist ein Zeiger auf signed char oder unsigned char.
j Wie bei h, aber der nächste Zeiger ist ein Zeiger auf intmax_t oder uintmax_t. Dieser Veränderer
wurde in C99 eingeführt.
l Zeigt an, dass die Umwandlung eine aus d, i, o, u, x, X, n sein wird und dass der nächste Zeiger
ein Zeiger auf long oder unsigned long (anstelle von int) ist oder dass die Umwandlung eine aus e,
f, g sein wird und dass der nächste Zeiger ein Zeiger auf double (anstelle von float) ist. Falls
zusammen mit %c oder %s verwandt, wird der entsprechende Parameter als Zeiger auf ein weites
Zeichen bzw. eine Zeichenkette weiter Zeichen betrachtet.
ll (ell-ell) Zeigt an, dass die Umwandlung eine aus b, d, i, o, u, x, X, n sein wird und dass der
nächste Zeiger ein Zeiger auf long long oder unsigned long long (anstelle von int) sein wird.
L Zeigt an, dass die Umwandlung eine aus e, f, or g sein wird und dass der nächste Zeiger ein Zeiger
auf long double sein wird oder (als GNU-Erweiterung) die Umwandlung eine aus d, i, o, u, x und
dass der nächste Zeiger ein Zeiger auf long long sein wird.
q äquivalent zu L. Dieser Kennzeichner existiert in ANSI C nicht.
t Wie bei h, aber der nächste Zeiger ist ein Zeiger auf ptrdiff_t. Dieser Veränderer wurde in C99
eingeführt.
z Wie bei h, aber der nächste Zeiger ist ein Zeiger auf size_t. Dieser Veränderer wurde in C99
eingeführt.
Die folgenden Umwandlungskennzeichner sind verfügbar:
% Passt auf ein wörtliches »%«. Das heißt, %% in der Formatzeichenkette passt auf ein einzelnes
Eingabezeichen »%«. Es erfolgt keine Umwandlung (aber anfängliche Leerraumzeichen werden
verworfen) und keine Zuweisung.
d Passt auf eine optional vorzeichenbehaftete Ganzzahl; der nächste Zeiger muss ein Zeiger auf int
sein.
i Passt auf eine optional vorzeichenbehaftete Ganzzahl; der nächste Zeiger muss ein Zeiger auf int
sein. Die Ganzzahl wird zur Basis 16 gelesen, falls sie mit 0x oder 0X anfängt; zur Basis 8, falls
sie mit 0 beginnt und ansonsten zur Basis 10. Es werden nur Zeichen verwandt, die der Basis
entsprechen.
o Passt auf eine vorzeichenlose oktale Ganzzahl; der nächste Zeiger muss ein Zeiger auf unsigned int
sein.
u Passt auf eine vorzeichenlose dezimale Ganzzahl; der nächste Zeiger muss ein Zeiger auf unsigned
int sein.
x Passt auf eine vorzeichenlose hexadezimale Ganzzahl (die optional mit einem Präfix 0x oder 0X
beginnt, der verworfen wird); der nächste Zeiger muss ein Zeiger auf unsigned int sein.
X Äquivalent zu x.
f Passt auf eine optional vorzeichenbehaftete Fließkommazahl; der nächste Zeiger muss ein Zeiger auf
float sein.
e Äquivalent zu f.
g Äquivalent zu f.
E Äquivalent zu f.
a (C99) Äquivalent zu f.
s Passt auf eine Sequenz von nicht-Leerraum-Zeichen; der nächste Zeiger muss ein Zeiger auf ein
anfängliches Element eines Zeichenfeldes sein, das lang genug ist, um die Eingabesequenz und das
abschließende Nullbyte (»\0«), das automatisch hinzugefügt wird, aufzunehmen. Die
Eingabezeichenkette stoppt beim Leerraum oder bei der maximalen Feldbreite, je nachdem, was zuerst
erreicht wird.
c Passt auf eine Sequenz von Zeichen, deren Länge durch die maximale Feldbreite (standardmäßig 1)
festgelegt ist; der nächste Zeiger muss ein Zeiger auf ein char sein und es muss genug Platz für
alle Zeichen sein (es wird kein abschließendes Nullbyte hinzugefügt). Das gewöhnliche Überspringen
anfänglichen Leerraums wird unterdrückt. Um zuerst Leerraum zu überspringen, verwenden Sie ein
explizites Leerzeichen in dem Format.
[ Passt auf eine nicht leere Zeichensequenz aus der angegebenen Menge von akzeptierten Zeichen; der
nächste Zeiger muss ein Zeiger auf ein char sein und es muss genug Platz für alle Zeichen in der
Zeichenkette sowie des abschließende Nullbytes sein. Das gewöhnliche Überspringen anfänglichen
Leerraums wird unterdrückt. Die Zeichenkette muss aus Zeichen in (oder nicht in) der bestimmten
Menge sein; die Menge wird durch die Zeichen zwischen der öffnenden eckigen Klammer [ und der
schließenden eckigen Klammer ] definiert. Die Menge schließt diese Zeichen aus, falls das erste
Zeichen nach der öffnenden eckigen Klammer ein Zirkumflex (^) ist. Um eine schließende Klammer in
die Menge aufzunehmen, verwenden Sie es als erstes Zeichen nach der öffnenden eckigen Klammer oder
dem Zirkumflex, an jeder anderen Position wird sie die Menge schließen. Der Gedankenstrich - ist
auch besonders; wird er zwischen zwei andere Zeichen gestellt, fügt er alle dazwischen liegenden
Zeichen zu der Menge hinzu. Um einen Gedankenstrich in die Menge aufzunehmen, stellen Sie ihn als
letztes Zeichen vor die finale schließende eckige Klammer. Beispielsweise bedeutet [^]0-9-] die
Menge »alles außer die schließende eckige Klammer, Null bis Neun und Gedankenstrich«. Die
Zeichenkette endet mit dem Auftauchen eines Zeichens, das nicht in der Menge ist, oder (falls ein
Zirkumflex verwandt wird) das in der Menge liegt oder wenn die Feldlänge erreicht wird.
p Passt auf einen Zeigerwert (wie von %p in printf(3) ausgegeben); der nächste Zeiger muss ein
Zeiger auf ein void sein.
n Es wird nichts erwartet, stattdessen wird die Anzahl der bisher aus der Eingabe verbrauchten
Zeichen durch den nächsten Zeiger gespeichert, der ein Zeiger auf int oder eine Variante sein
muss, deren Größe auf den (optionalen) ganzzahligen Längenveränderer passt. Dies ist keine
Umwandlung und vergrößert nicht die durch die Funktion zurückgelieferte Anzahl. Diese Zuweisung
kann mit dem Zuweisungs-Unterdrückungszeichen * unterdrückt werden, aber die Auswirkung auf den
Rückgabewert ist nicht definiert. Daher sollten %*n-Umwandlungen nicht verwandt 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ückgeliefert, falls das Eingabeende erreicht wird, bevor entweder die erste
erfolgreiche Umwandlung erfolgte oder ein »matching failure« auftrat.
FEHLER
EILSEQ Eingabe-Byteabfolge bildet kein gültiges Zeichen.
EINVAL Nicht genug Argumente oder format ist NULL.
ENOMEM Speicher aufgebraucht.
ATTRIBUTE
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
┌────────────────────────────────────────────────────────────┬───────────────────────┬──────────────────┐
│ Schnittstelle │ Attribut │ Wert │
├────────────────────────────────────────────────────────────┼───────────────────────┼──────────────────┤
│ sscanf(), vsscanf() │ Multithread-Fähigkeit │ MT-Sicher locale │
└────────────────────────────────────────────────────────────┴───────────────────────┴──────────────────┘
STANDARDS
C11, POSIX.1-2008.
GESCHICHTE
C89, POSIX.1-2001.
Der Umwandlungskennzeichner q ist die 4.4BSD-Notation für long long, während ll oder die Verwendung von L
in Ganzzahlumwandlungen die GNU-Notation ist.
Die Linux-Version dieser Funktionen basiert auf der Bibliothek GNU libio. Schauen Sie in die
info(1)-Dokumentation von GNU libc (glibc-1.08) für eine prägnantere Beschreibung.
ANMERKUNGEN
Der »a«-Zuweisung-Reservierungs-Veränderer
Ursprünglich unterstützte die GNU-C-Bibliothek dynamische Reservierungen für Zeichenketteneingaben (als
nicht standardisierte Erweiterung) mittels des Zeichens a. (Diese Funktionalität ist seit mindestens
Glibc 2.0 vorhanden). Daher könnte nachfolgendes geschrieben werden, damit sscanf() einen Puffer für eine
Zeichenkette reserviert, wobei ein Zeiger auf diesen Puffer in *buf zurückgeliefert wird:
char *buf;
sscanf(str, "%as", &buf);
Die Verwendung des Buchstabens a für diesen Zweck war problematisch, da a durch die ISO-C-Norm auch als
Synonym für f (Fließkommazahleneingabe) definiert ist. POSIX.1-2008 spezifiziert stattdessen den
Modifikator m für die Zuweisungsreservierung (wie in obiger 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 es wurde auch _GNU_SOURCE angegeben). In diesem Fall wird a
als Kennzeichner für Fließkommazahlen interpretiert (siehe oben).
Die Unterstützung für den Kennzeichner m wurde in Glibc 2.7 hinzugefügt und neue Programme sollten diesen
Modifikator anstelle von a verwenden.
Neben der Standardisierung durch POSIX hat der Modifikator m die folgenden zusätzlichen Vorteile
gegenüber der Verwendung von a:
• Er kann auch in Umwandlungskennzeichnern %c verwandt werden (z.B. %3mc).
• Er vermeidet Mehrdeutigkeiten in Hinblick auf den Fließommazahlen-Umwandlungskennzeichner %a (und ist
nicht von gcc -std=c99 usw. betroffen).
FEHLER
Numerische Umwandlungskennzeichner
Die Verwendung von numerischen Umwandlungskennzeichnern erzeugt nicht definiertes Verhalten für ungültige
Eingabe. Siehe C11 7.21.6.2/10. Dies ist ein Fehler in der ISO-C-Norm und keine immanente Eigenschaft mit
dem API. Allerdings sind aktuelle Implementierungen nicht vor dem Fehler gefeit, daher wird deren
Verwendung nicht empfohlen. Stattdessen sollten Programme Funktionen wie strtol(3) verwenden, um
numerische Eingabe auszuwerten. Alternativ entschärfen Sie dies durch Angabe einer maximalen Feldbreite.
Nicht standardisierte Modifikatoren
Diese Funktionen sind vollständig C99-konform, bieten aber die zusätzlichen Modifikatoren q und a sowie
zusätzliches Verhalten der Modifikatoren L und ll an. Letzteres kann als Fehler angesehen werden, da es
das in C99 definierte Verhalten der Modifikatoren ändert.
Einige Kombinationen der in C99 definierten Typ-Modifikatoren und Umwandlungskennzeichner ergeben keinen
Sinn (z.B. %Ld). Obwohl sie unter Linux ein gut definiertes Verhalten haben könnten, muss dies auf
anderen Architekturen nicht der Fall sein. Daher ist es normalerweise besser, Modifikatoren zu verwenden,
die überhaupt nicht durch C99 definiert sind, d.h. q anstelle von L in Kombination mit den Umwandlungen
d, i, o, u, x und X oder ll.
Die Verwendung von q ist nicht identisch zu der auf 4.4BSD, da es in »float«-Umwandlungen äquivalent zu L
verwandt werden kann.
BEISPIELE
Um den dynamischen Reservierungs-Umwandlungskennzeichner zu verwenden, geben Sie m als Längenmodifikator
an (daher %ms oder %m[Bereich]). Der Aufrufende muss free(3) für die zurückgelieferte Zeichenkette
aufrufen, wie im folgenden Beispiel:
char *p;
int n;
errno = 0;
n = sscanf(str, "%m[a-z]", &p);
if (n == 1) {
printf("gelesen: %s\n", p);
free(p);
} else if (errno != 0) {
perror("sscanf");
} else {
fprintf(stderr, "Keine passenden Zeichen\n");
}
Wie im obigen Beispiel gezeigt, ist der Aufruf von free(3) nur notwendig, wenn der Aufruf sscanf()
erfolgreich eine Zeichenkette gelesen hat.
SIEHE AUCH
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von Helge Kreutzmann <debian@helgefjell.de> erstellt.
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 die
Mailingliste der Übersetzer: debian-l10n-german@lists.debian.org.
Linux man-pages 6.9.1 15. Juni 2024 sscanf(3)