sscanf(3) Library Functions Manual sscanf(3) BEZEICHNUNG sscanf, vsscanf - Formatumwandlungen von Eingabezeichenketten BIBLIOTHEK Standard-C-Bibliothek (libc, -lc) UBERSICHT #include int sscanf(const char *restrict zeichenkette, const char *restrict format, ); #include 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 fur den Ruckgabewert der zugehorigen Umwandlungsspezifikation haben. Falls die Anzahl der Umwandlungsspezifikationen in format die Anzahl der Zeiger-Argumente ubersteigt, sind die Ergebnisse undefiniert. Falls die Anzahl der Zeiger-Argumente die Anzahl der Umwandlungsspezifikationen ubersteigt, werden die uberzahligen Zeiger-Argumente ausgewertet, aber ansonsten ignoriert. sscanf() Diese Funktionen lesen ihre Eingabe aus der Zeichenkette, auf die zeichenkette zeigt. Die Funktion vsscanf() verhalt 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 fehlschlagt, werden keine weiteren Eingaben gelesen und sscanf() kehrt zuruck. Ein >>Fehlschlagen<< kann Folgendes sein: input failure bedeutet, dass Eingabezeichen nicht verfugbar sind. matching failure heisst, dass die Eingabe ungeeignet war (siehe unten). Eine Richtlinie kann Folgendes sein: o eine Abfolge von Leerraumen (Leerzeichen, Tabulator, Zeilenvorschub, etc.; siehe isspace(3)). Diese Richtlinie passt auf jede Menge von Leerraumen, einschliesslich keinem, in der Eingabe. o ein normales Zeichen (d.h. ein anderes, als ein Leerraum oder >>%<<). Dieses Zeichen muss exakt mit dem nachsten Zeichen der Eingabe ubereinstimmen. o eine Umwandlungsspezifikation, die mit dem Zeichen >>%<< (Prozent) beginnt. Eine Abfolge von Zeichen wird gemass dieser Spezifikation umgewandelt und das Ergebnis wird in das zugehorige Zeiger-Argument platziert. Falls das nachste Element nicht der Umwandlungsspezifikation entspricht, schlagt die Umwandlung fehl -- dies ist ein matching failure. Jede Umwandlungsspezifikation in format fangt entweder mit dem Zeichen >>%<< an oder der Zeichensequenz >>%n$<< (siehe unten fur die Unterscheidung) gefolgt von: o einem optionalen >>*<<-Zeichen zur Unterdruckung der Zuweisung: sscanf() liest die Eingabe gemass der Umwandlungsspezifikation, verwirft aber die Eingabe. Es wird kein zugehoriges Zeiger-Argument benotigt und diese Spezifikation ist nicht in der Anzahl der erfolgreichen Zuweisungen enthalten, die von sscanf() zuruckgegeben werden. o einem optionalen englischen Anfuhrungszeichen (') fur 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 >>*<<-Zuweisungsunterdruckungszeichen folgen oder ihm vorangehen. o einem optionalen >>m<<-Zeichen. Dies wird mit Zeichenkettenumwandlungen benutzt (%s, %c, %[) und entlastet den Aufrufenden von der Notwendigkeit, einen zugehorigen Puffer zu reservieren, der die Eingabe erhalt: Stattdessen reserviert sscanf() einen Puffer von ausreichender Grosse und weist die Adresse dieses Puffers dem zugehorigen 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 langer benotigt wird. o 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 Leerraume am Anfang (die Ausnahmen sind nachfolgend vermerkt). Diese verworfenen Zeichen werden nicht bei der Berechnung der maximalen Feldbreite mitgezahlt. Eingabeumwandlung von Zeichenketten speichert ein abschliessendes Nullbyte (>>\0<<), um das Ende der Eingabe zu kennzeichnen; die maximale Feldbreite enthalt dieses Endezeichen nicht. o Ein optionales Typveranderungszeichen. Beispielsweise wird der Typveranderer l mit Ganzzahlumwandlungen wie %d verwandt, um festzulegen, dass sich das entsprechende Zeiger-Argument auf ein long anstelle eines Zeigers auf ein int bezieht. o Ein Umwandlungskennzeichner, der die Art der durchzufuhrende 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, ausser dass eine Zeichenkette, die >>%n$<<-Angaben enthalt %% und %* enthalten kann. Falls format >>%<<-Angaben enthalt, 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 Typveranderungszeichen konnen in einer Umwandlungsfestlegung auftauchen: h Zeigt an, dass die Umwandlung eine aus d, i, o, u, x, X, n sein wird und dass der nachste Zeiger ein Zeiger auf short oder unsigned short (anstelle von int) ist. hh Wie bei h, aber der nachste Zeiger ist ein Zeiger auf signed char oder unsigned char. j Wie bei h, aber der nachste Zeiger ist ein Zeiger auf intmax_t oder uintmax_t. Dieser Veranderer wurde in C99 eingefuhrt. l Zeigt an, dass die Umwandlung eine aus d, i, o, u, x, X, n sein wird und dass der nachste 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 nachste 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 nachste 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 nachste Zeiger ein Zeiger auf long double sein wird oder (als GNU-Erweiterung) die Umwandlung eine aus d, i, o, u, x und dass der nachste Zeiger ein Zeiger auf long long sein wird. q aquivalent zu L. Dieser Kennzeichner existiert in ANSI C nicht. t Wie bei h, aber der nachste Zeiger ist ein Zeiger auf ptrdiff_t. Dieser Veranderer wurde in C99 eingefuhrt. z Wie bei h, aber der nachste Zeiger ist ein Zeiger auf size_t. Dieser Veranderer wurde in C99 eingefuhrt. Die folgenden Umwandlungskennzeichner sind verfugbar: % Passt auf ein wortliches >>%<<. Das heisst, %% in der Formatzeichenkette passt auf ein einzelnes Eingabezeichen >>%<<. Es erfolgt keine Umwandlung (aber anfangliche Leerraumzeichen werden verworfen) und keine Zuweisung. d Passt auf eine optional vorzeichenbehaftete Ganzzahl; der nachste Zeiger muss ein Zeiger auf int sein. i Passt auf eine optional vorzeichenbehaftete Ganzzahl; der nachste Zeiger muss ein Zeiger auf int sein. Die Ganzzahl wird zur Basis 16 gelesen, falls sie mit 0x oder 0X anfangt; 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 nachste Zeiger muss ein Zeiger auf unsigned int sein. u Passt auf eine vorzeichenlose dezimale Ganzzahl; der nachste Zeiger muss ein Zeiger auf unsigned int sein. x Passt auf eine vorzeichenlose hexadezimale Ganzzahl (die optional mit einem Prafix 0x oder 0X beginnt, der verworfen wird); der nachste Zeiger muss ein Zeiger auf unsigned int sein. X Aquivalent zu x. f Passt auf eine optional vorzeichenbehaftete Fliesskommazahl; der nachste Zeiger muss ein Zeiger auf float sein. e Aquivalent zu f. g Aquivalent zu f. E Aquivalent zu f. a (C99) Aquivalent zu f. s Passt auf eine Sequenz von nicht-Leerraum-Zeichen; der nachste Zeiger muss ein Zeiger auf ein anfangliches Element eines Zeichenfeldes sein, das lang genug ist, um die Eingabesequenz und das abschliessende Nullbyte (>>\0<<), das automatisch hinzugefugt 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 Lange durch die maximale Feldbreite (standardmassig 1) festgelegt ist; der nachste Zeiger muss ein Zeiger auf ein char sein und es muss genug Platz fur alle Zeichen sein (es wird kein abschliessendes Nullbyte hinzugefugt). Das gewohnliche Uberspringen anfanglichen Leerraums wird unterdruckt. Um zuerst Leerraum zu uberspringen, verwenden Sie ein explizites Leerzeichen in dem Format. [ Passt auf eine nicht leere Zeichensequenz aus der angegebenen Menge von akzeptierten Zeichen; der nachste Zeiger muss ein Zeiger auf ein char sein und es muss genug Platz fur alle Zeichen in der Zeichenkette sowie des abschliessende Nullbytes sein. Das gewohnliche Uberspringen anfanglichen Leerraums wird unterdruckt. Die Zeichenkette muss aus Zeichen in (oder nicht in) der bestimmten Menge sein; die Menge wird durch die Zeichen zwischen der offnenden eckigen Klammer [ und der schliessenden eckigen Klammer ] definiert. Die Menge schliesst diese Zeichen aus, falls das erste Zeichen nach der offnenden eckigen Klammer ein Zirkumflex (^) ist. Um eine schliessende Klammer in die Menge aufzunehmen, verwenden Sie es als erstes Zeichen nach der offnenden eckigen Klammer oder dem Zirkumflex, an jeder anderen Position wird sie die Menge schliessen. Der Gedankenstrich - ist auch besonders; wird er zwischen zwei andere Zeichen gestellt, fugt 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 schliessende eckige Klammer. Beispielsweise bedeutet [^]0-9-] die Menge >>alles ausser die schliessende 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 Feldlange erreicht wird. p Passt auf einen Zeigerwert (wie von %p in printf(3) ausgegeben); der nachste 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 nachsten Zeiger gespeichert, der ein Zeiger auf int oder eine Variante sein muss, deren Grosse auf den (optionalen) ganzzahligen Langenveranderer passt. Dies ist keine Umwandlung und vergrossert nicht die durch die Funktion zuruckgelieferte Anzahl. Diese Zuweisung kann mit dem Zuweisungs-Unterdruckungszeichen * unterdruckt werden, aber die Auswirkung auf den Ruckgabewert ist nicht definiert. Daher sollten %*n-Umwandlungen nicht verwandt werden. RUCKGABEWERT Bei Erfolg geben diese Funktionen die Anzahl der Eingabeelemente zuruck, die erfolgreich ubereinstimmten und zugewiesen wurden. Dies konnen weniger sein, als bereitgestellt wurden oder null, wenn ein >>matching failure<< auftrat. Der Wert EOF wird zuruckgeliefert, falls das Eingabeende erreicht wird, bevor entweder die erste erfolgreiche Umwandlung erfolgte oder ein >>matching failure<< auftrat. FEHLER EILSEQ Eingabe-Byteabfolge bildet kein gultiges Zeichen. EINVAL Nicht genug Argumente oder format ist NULL. ENOMEM Speicher aufgebraucht. ATTRIBUTE Siehe attributes(7) fur eine Erlauterung der in diesem Abschnitt verwandten Ausdrucke. +-------------------------+-------------------------+------------------+ |Schnittstelle | Attribut | Wert | +-------------------------+-------------------------+------------------+ |sscanf(), vsscanf() | Multithread-Fahigkeit | MT-Sicher locale | +-------------------------+-------------------------+------------------+ STANDARDS C11, POSIX.1-2008. GESCHICHTE C89, POSIX.1-2001. Der Umwandlungskennzeichner q ist die 4.4BSD-Notation fur long long, wahrend 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) fur eine pragnantere Beschreibung. ANMERKUNGEN Der >>a<<-Zuweisung-Reservierungs-Veranderer Ursprunglich unterstutzte die GNU-C-Bibliothek dynamische Reservierungen fur Zeichenketteneingaben (als nicht standardisierte Erweiterung) mittels des Zeichens a. (Diese Funktionalitat ist seit mindestens Glibc 2.0 vorhanden). Daher konnte nachfolgendes geschrieben werden, damit sscanf() einen Puffer fur eine Zeichenkette reserviert, wobei ein Zeiger auf diesen Puffer in *buf zuruckgeliefert wird: char *buf; sscanf(str, "%as", &buf); Die Verwendung des Buchstabens a fur diesen Zweck war problematisch, da a durch die ISO-C-Norm auch als Synonym fur f (Fliesskommazahleneingabe) definiert ist. POSIX.1-2008 spezifiziert stattdessen den Modifikator m fur die Zuweisungsreservierung (wie in obiger BESCHREIBUNG dokumentiert). Beachten Sie, dass der Modifikator a nicht verfugbar ist, falls das Programm mit gcc -std=c99 oder gcc -D_ISOC99_SOURCE kompiliert wurde (ausser es wurde auch _GNU_SOURCE angegeben). In diesem Fall wird a als Kennzeichner fur Fliesskommazahlen interpretiert (siehe oben). Die Unterstutzung fur den Kennzeichner m wurde in Glibc 2.7 hinzugefugt und neue Programme sollten diesen Modifikator anstelle von a verwenden. Neben der Standardisierung durch POSIX hat der Modifikator m die folgenden zusatzlichen Vorteile gegenuber der Verwendung von a: o Er kann auch in Umwandlungskennzeichnern %c verwandt werden (z.B. %3mc). o Er vermeidet Mehrdeutigkeiten in Hinblick auf den Fliessommazahlen-Umwandlungskennzeichner %a (und ist nicht von gcc -std=c99 usw. betroffen). FEHLER Numerische Umwandlungskennzeichner Die Verwendung von numerischen Umwandlungskennzeichnern erzeugt nicht definiertes Verhalten fur ungultige 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 entscharfen Sie dies durch Angabe einer maximalen Feldbreite. Nicht standardisierte Modifikatoren Diese Funktionen sind vollstandig C99-konform, bieten aber die zusatzlichen Modifikatoren q und a sowie zusatzliches Verhalten der Modifikatoren L und ll an. Letzteres kann als Fehler angesehen werden, da es das in C99 definierte Verhalten der Modifikatoren andert. 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 konnten, muss dies auf anderen Systemen nicht der Fall sein. Daher ist es normalerweise besser, Modifikatoren zu verwenden, die uberhaupt 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 aquivalent zu L verwandt werden kann. BEISPIELE Um den dynamischen Reservierungs-Umwandlungskennzeichner zu verwenden, geben Sie m als Langenmodifikator an (daher %ms oder %m[Bereich]). Der Aufrufende muss free(3) fur die zuruckgelieferte 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) UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Helge Kreutzmann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.12 17. November 2024 sscanf(3)