Parameter | format ist eine Zeichenkette, die in ihrem anfänglichen Umschaltmodus beginnt und endet, (sofern ein Umschaltmodus definiert ist) und keine, eine oder mehrere Umwandlungsanweisungen enthält. format kann drei Arten von Zeichen enthalten: Zeichen vom Typ wchar_t (aber kein Zwischenraumzeichen oder %), die 1 : 1 in den Ausgabedatenstrom kopiert werden. Zwischenraumzeichen, beginnend mit einem Gegenschrägstrich (\) (siehe iswspace). Umwandlungsanweisungen, beginnend mit dem Prozentzeichen (%), von denen jede keinem, einem oder mehreren Argumenten in arglist zugeordnet wird. Wenn in arglist weniger Argumente übergeben werden, als in format festgelegt sind, ist das Ergebnis undefiniert. Wenn in format weniger Argumente festgelegt sind, als in arglist übergeben werden, werden die überflüssigen Argumente ignoriert.
Die wscanf-Funktionen lesen das Eingabezeichen zunächst ohne es umzuwandeln und in einer Variablen abzuspeichern. Stimmt das Eingabezeichen nicht mit dem in format angegebenen Zeichen überein, wird die Eingabebearbeitung abgebrochen und die Funktion kehrt zurück. Wenn die Umwandlung wegen eines nicht passenden Langzeichens abbricht, verbleibt dieses Zeichen ungelesen im Eingabestrom. Die Formatzeichenkette format kann beliebig viele oder keine Zwischenraumzeichen enthalten. Diese Zeichen haben keine Steuerfunktion. Zwischenraumzeichen in der Eingabe werden als Trennzeichen zwischen Eingabefeldern behandelt und nicht mit umgewandelt (Ausnahme siehe %c, %n und %[]). Führende Zwischenraumzeichen werden bei der Eingabe ignoriert. Alle Formen von fwscanf erlauben das Erkennen eines landessprach-spezifischen Dezimalzeichens in der Eingabezeichenkette. Das Dezimalzeichen wird durch die Lokalität des Progamms definiert (Kategorie LC_NUMERIC). In der Lokalität POSIX oder einer Lokalität, bei der das Dezimalzeichen nicht definiert ist, ist das Dezimalzeichen auf . (Punkt) voreingestellt. Jede Umwandlungsanweisung muss mit einem Prozentzeichen (%) beginnen; darauf folgen: Ein optionales Langzeichen Stern (*) zum Überspringen einer Zuweisung. Eine optionale Ganzzahl (Dezimalziffern) ungleich 0, welche die maximale Feldbreite angibt. Ein optionales hh, h, l, ll, L, j, z oder t, das die Größe des aufnehmenden Objekts angibt:
l vor den Umwandlungszeichen c, s und [ : das entsprechende Argument ist ein Zeiger auf wchar_t .
hh bzw. h bzw. l vor d, i und n : das entsprechende Argument ist ein Zeiger auf signed char (hh) bzw. short int (h) bzw. long int (l).
hh bzw. h bzw. l vor o, u, x und X : das entsprechende Argument ist ein Zeiger auf unsigned char (hh) bzw. unsigned short int (h) bzw. unsigned long int (l).
ll vor d, i und n : das entsprechende Argument ist ein Zeiger auf long long int.
ll vor o, u, x und X : das entsprechende Argument ist ein Zeiger auf unsigned long long int.
l bzw. L vor a, A, e, E, f, F, g und G : das entsprechende Argument ist ein Zeiger auf double (l) bzw.long double (L).
j vor o, u, x und X: Umwandlung eines Arguments vom Typ Zeiger auf uintmax_t.
j vor d, i und n: Umwandlung eines Arguments vom Typ Zeiger auf intmax_t.
z vor o, u, x und X: Umwandlung eines Arguments vom Typ Zeiger auf size_t.
z vor d, i und n: Umwandlung eines Arguments vom Typ Zeiger auf long int.
t vor o, u, x und X: Umwandlung eines Arguments vom Typ Zeiger auf unsigned long int.
t vor d, i und n: Umwandlung eines Arguments vom Typ Zeiger auf ptrdiff_t. Wenn hh, h, l, ll, L, j, z oder t vor einem anderen Umwandlungszeichen steht, ist das Verhalten undefiniert. Ein Umwandlungszeichen, das den Typ der durchzuführenden Umwandlung angibt.
fwscanf führt jede Anweisung einzeln aus. Wenn eine Anweisung fehlschlägt, wie unten genauer erläutert, kehrt die Funktion zurück. Fehler werden als Eingabefehler bezeichnet, wenn Eingabezeichen fehlen, oder als Formatfehler, wenn Eingabezeichen nicht zu dem Format passen.
Eine Anweisung, die aus einem Zwischenraumzeichen besteht, wird so ausgeführt, dass die Eingabe bis zum ersten Langzeichen gelesen wird, das kein Zwischenraumzeichen ist (dieses Langzeichen selbst wird nicht gelesen) oder bis keine Langzeichen mehr gelesen werden können (EOF). Eine Anweisung, die aus einem normalen Langzeichen besteht, wird ausgeführt, indem das nächste Langzeichen aus der Eingabe gelesen wird. Wenn dieses Langzeichen nicht mit dem vorgegebenen Langzeichen übereinstimmt, schlägt die Anweisung fehl und das unpassende und alle nachfolgenden Langzeichen werden nicht gelesen. Eine Anweisung, die eine Umwandlungsanweisung ist, definiert eine Menge von passenden Eingabefolgen, wie dies unten für jede einzelne Umwandlungsanweisung beschrieben wird. Eine Umwandlungsanweisung wird in den folgenden Schritten ausgeführt: Die Eingabe von Zwischenraumzeichen wird überlesen, solange die Anweisung weder ein [ noch eines der Umwandlungszeichen c oder n enthält. Eingabeelemente werden aus der Eingabe gelesen, solange die Anweisung nicht das Umwandlungszeichen n enthält. Ein Eingabeelement ist definiert als die längste Folge von Eingabezeichen (bis zu einer eventuell angegebenen maximalen Feldbreite), die ein Anfang einer passenden Folge ist. Das erste Langzeichen nach einem Eingabeelement bleibt, sofern es vorhanden ist, ungelesen. Wenn die Länge des Eingabeelements gleich 0 ist, schlägt die Ausführung der Anweisung fehl; diese Bedingung bedeutet einen Formatfehler, sofern nicht ein Eingabefehler wie zum Beispiel EOF oder das Auftreten eines Lese-Fehlers weitere Eingaben verhindert. Sofern nicht das Umwandlungszeichens % angegeben ist, wird das Eingabeelement (bzw. bei %n die Anzahl der gelesenen Eingabezeichen), umgewandelt in einen Datentyp, der dem Umwandlungszeichen entspricht. Wenn das Eingabeelement nicht zu der Umwandlungsanweisung passt, schlägt die Ausführung dieser Anweisung mit einem Formatfehler fehl. Passt das Eingabeelement, wird - sofern die Zuweisung nicht durch das Zeichen * unterdrückt wird - das Ergebnis der Umwandlung in dem Objekt abgelegt, welches das erste auf format folgende Argument ist, in dem bisher noch kein Umwandlungsergebnis abgelegt wurde. Wenn dieses Objekt nicht den passenden Datentyp hat oder wenn das Ergebnis der Umwandlung nicht in dem zur Verfügung stehenden Platz dargestellt werden kann, ist das Verhalten undefiniert. Umwandlungsanweisungen sehen also wie folgt aus: % [*] [m] { [hh|h|l|ll|j|z|t]{d|i|o|n|u|x|X} |
[l]{c|s} |
[l|L]{e|E|f|g|G} |
p |
[l]{[...]|[^...]} |
%
}
| d
| Liest eine optional mit einem Vorzeichen versehene dezimale Ganzzahl ein, deren Format dasselbe ist, das die Funktion wcstol erwartet (base = 10). Das zugehörige Argument sollte ein Zeiger auf int sein. | i
| Liest eine optional mit einem Vorzeichen versehene dezimale Ganzzahl ein, deren Format dasselbe ist, das die Funktion wcstol erwartet (base = 8). Das entsprechende Argument sollte vom Typ Zeiger auf int sein. | o
| Liest eine optional mit einem Vorzeichen versehene oktale Ganzzahl ein, deren Format dasselbe ist, das die Funktion wcstoul erwartet (base = 8). Das entsprechende Argument sollte vom Typ Zeiger auf unsigned integer sein. | u
| Liest eine optional mit einem Vorzeichen versehene dezimale Ganzzahl ein, deren Format dasselbe ist, das die Funktion wcstoul erwartet (base = 10). Das entsprechende Argument sollte vom Typ Zeiger auf unsigned integer sein. | x, X
| Liest eine optional mit einem Vorzeichen versehene hexadezimale Ganzzahl ein, deren Format dasselbe ist, das die Funktion wcstoul erwartet (ba- se = 16). Das entsprechende Argument sollte vom Typ Zeiger auf unsigned integer sein. | a, A, e, E, f, F, g, G
|
| Diese Umwandlungszeichen lesen eine optional mit einem Vorzeichen versehene Gleitpunktzahl ein. Deren Format ist dasselbe, das auch wcstod erwartet. Das entsprechende Argument sollte vom Typ Zeiger auf float sein. | s
| Liest eine Folge von Langzeichen ein, die keine Zwischenraumzeichen sind.
Ist kein l angegeben, werden Zeichen aus dem Eingabefeld so konvertiert wie bei Aufrufen der Funktion wcrtomb. Der Konversions-Status wird dabei in einem Objekt vom Typ mbstate_t beschrieben und mit 0 initialisiert, bevor das erste Langzeichen konvertiert wird. Es wird bis zum abschließenden Nullzeichen geschrieben.Das entsprechende Argument sollte ein Zeiger ein char-Feld sein, das groß genug ist, um die konvertierte Folge und ein abschließendes Nullzeichen aufzunehmen, das automatisch angefügt wird.
Ist l angegeben, sollte das entsprechende Argument ein Zeiger auf das erste Element eines wchar_t-Feldes sein, das groß genug ist, um die Folge und ein abschließendes Nullzeichen aufzunehmen, das automatisch angefügt wird. | [
| Liest eine nichtleere Folge von Langzeichen aus einer Menge von erwarteten Langzeichen (der Eingabemenge).
Ist kein l angegeben, werden Zeichen aus dem Eingabefeld so konvertiert wie bei Aufrufen der Funktion wcrtomb. Der Konversions-Status wird dabei in einem Objekt vom Typ mbstate_t beschrieben und mit 0 initialisiert, bevor das erste Langzeichen konvertiert wird. Es wird bis zum abschließenden Nullzeichen geschrieben.Das entsprechende Argument sollte ein Zeiger ein char-Feld sein, das groß genug ist, um die konvertierte Folge und ein abschließendes Nullzeichen aufzunehmen, das automatisch angefügt wird.
Ist l angegeben, sollte das entsprechende Argument ein Zeiger auf das erste Element eines wchar_t-Feldes sein, das groß genug ist, um die Folge und ein abschließendes Nullzeichen aufzunehmen, das automatisch angefügt wird.
Die Umwandlungsanweisung umfasst alle auf [ folgenden Langzeichen in der Zeichenkette format bis einschließlich der zugehörigen schließenden eckigen Klammer ]. Die Langzeichen zwischen den Klammern stellen die Eingabemenge dar, sofern nicht das erste Langzeichen nach der linken Klammer das Zeichen ^ ist. In diesem Fall enthält die Eingabemenge alle Langzeichen, die nicht in der Liste zwischen dem Zeichen ^ und der Klammer ] aufgeführt sind.
Als Sonderfall gilt, dass die rechte eckige Klammer in den beiden Fällen, in denen die Umwandlungsanweisung mit den Zeichenketten [] bzw. [^] beginnt, zur Eingabemenge gehört und erst die nächste rechte eckige Klammer diejenige ist, welche die Umwandlungsanweisung abschließt. Wenn das Zeichen - in der Liste auftritt und weder das letzte Zeichen noch das erste Zeichen nach [ bzw. [^ ist, dann ist das Verhalten undefiniert. | c
| Liest eine Folge von Langzeichen, deren Anzahl durch die Feldbreite bestimmt wird. Ist keine Feldbreite angegeben, wird 1 Langzeichen gelesen. Ist kein l angegeben, werden Zeichen aus dem Eingabefeld so konvertiert wie bei Aufrufen der Funktion wcrtomb. Der Konversions-Status wird dabei in einem Objekt vom Typ mbstate_t beschrieben und mit 0 initialisiert, bevor das erste Langzeichen konvertiert wird. Das entsprechende Argument sollte ein Zeiger auf ein char-Feld sein, das groß genug ist, um die konvertierte Folge aufzunehmen. Es wird kein Nullzeichen angefügt.
Ist l angegeben, sollte das entsprechende Argument ein Zeiger auf das erste Element eines wchar_t-Feldes sein, das groß genug ist, um die Folge aufzunehmen Es wird kein Nullzeichen angefügt. Das Überlesen von Zwischenraumzeichen wird in diesem Fall unterdrückt; um das nächste Langzeichen zu lesen, das kein Zwischenraumzeichen ist, sollte %1s verwendet werden. | p
| Liest eine Menge von Folgen, die denen entsprechen sollten, die von der Umwandlungsanweisung %p der fwprintf-Funktionen erzeugt werden. Das entsprechende Argument sollte ein Zeiger auf einen Zeiger auf void sein. Die Interpretation des Eingabeelements ist jeweils implementierungsabhängig; für ein Eingabeelement, das nicht zuvor während derselben Programmausführung umgewandelt wurde, ist das Verhalten der Umwandlungsanweisung %p undefiniert. Dies gilt insbesondere für Zeigerausgaben, die von anderen Systemen erzeugt worden sind. | n
| Es wird keine Eingabe verarbeitet. Das entsprechende Argument sollte ein Zeiger auf int sein, in das die bisher von diesem Aufruf gelesene Zahl der Langzeichen eingetragen wird. Die Ausführung einer Anweisung des Typs % n erhöht nicht den Zuweisungszähler, der bei Beendigung der Ausführung der Funktion zurückgeliefert wird. | %
| Liest ein einzelnes %. Dabei findet keine Umwandlung oder Zuweisung statt. Die vollständige Umwandlungsanweisung lautet %%. | Wenn ein Umwandlungszeichen ungültig ist, ist das Verhalten von fwscanf undefiniert. Wenn das Dateiende während der Eingabe gefunden wird, wird die Umwandlung abgebrochen. Wenn das Dateiende auftritt, bevor irgendwelche, zur aktuellen Anweisung passenden Langzeichen gelesen wurden (abgesehen von zulässigen Zwischenraumzeichen), wird die Ausführung der aktuellen Anweisung mit einem Eingabefehler abgebrochen. Andernfalls wird, falls die Bearbeitung der aktuellen Anweisung nicht mit einem Formatfehler abbricht, eine von %n verschiedene darauffolgende Anweisung mit einem Eingabefehler abgebrochen. Wenn während eines swscanf-Aufrufs das Ende einer Zeichenkette erreicht wird, ist dies äquivalent zum Erreichen des Dateiendekennzeichens während eines fwscanf-Aufrufs. Abschließende Zwischenraumzeichen (einschließlich der Zeilenendezeichen) bleiben ungelesen, sofern nicht eine entsprechende Umwandlungsanweisung vorhanden ist. Der Erfolg des 1:1 Einlesens von Buchstaben und von unterdrückten Zuweisungen kann nicht direkt bestimmt werden, außer über die Anweisung % n. |
