Provided by: manpages-de-dev_4.23.1-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 ⟨https://port70.net/%7Ensz/c/c11/
n1570.html#7.21.6.2p10⟩. 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 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.