Manpages

NAAM

scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf − geformateerde invoer conversie

SAMENVATTING

#include <stdio.h>
int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *str, const char *format, ...);

#include <stdarg.h>
int vscanf(const char *format, va_list ap);
int vsscanf(const char *str, const char *format, va_list ap);
int vfscanf(FILE *stream, const char *format, va_list ap);

BESCHRIJVING

De functies in de scanf familie leest invoer volgens een format zoals onder beschreven. Dit format kan conversie specificaties bevatten; bij succes wordt het resultaat van de conversie opgeslagen onder het bijpassende pointer argument. De scanf functie leest invoer van de standaard invoer stream stdin, fscanf leest invoer van de invoer stream pointer stream, en sscanf leest zijn invoer van de karakter string waar str naar wijst.

De vfscanf functie lijkt op vfprintf(3), het leest invoer van de pointer stream, gebruik makend van een variabele lijst met pointer argumenten (zie stdarg(3)). De vscanf functie leest een variabele argumenten lijst van de standaard invoer en de vsscanf functie leest het van een string; deze lijken op de vprintf en vsprintf functies, respectievelijk.

Elk volgend pointer argument moet precies overeenkomen met elke volgende conversie specificatie (zie echter ook ’onderdrukken’ onder). Alle conversies starten met het % (procent teken) karakter. De format string mag ook andere karakters bevatten. Witte ruimte (zoals spaties, tabulaties, of nieuwe regels) in de format string, eten een willekeurige hoeveelheid witte ruimte weg in de input, inclusief geen witte ruimte. Al het andere in de format string moet overeenkomen met de invoer. Het (in)lezen stopt wanneer een invoer karakter niet met een format karakter overeenkomt. Het (in)lezen stopt ook wanneer een invoer conversie niet gemaakt kan worden (zie onder).

CONVERSIES

Op het % karakter dat een conversie introduceerd kunnen een aantal flag karakters volgen, als volgt:

*

Onderdrukt toewijzing. De conversie die volgt wordt afgehandeld, maar geen pointer wordt verbruikt; het resultaat van de conversie wordt genegeerd.

a

(glibc) Geeft aan dat de conversie s wordt gebruikt, de vereiste geheugen ruimte voor de string wordt aangevraagd via malloc, en de pointer er naar toe wordt toegekend aan de char pointer variabele. Deze pointer hoeft niet van te voren geinitialiseerd te worden. Deze vlag bestaat niet in ANSI C (C89) en heeft een andere betekenis in C99.

a

(C99) Gelijk aan f.

h

Geeft aan dat de conversie een van dioux of n zal zijn, en dat de volgende pointer een pointer naar een short int (in plaats van een int) zal zijn.

l

Geeft aan dat ofwel de conversie een van dioux of n en de volgende pointer een pointer naar een long int (in plaats van een int) zal zijn, ofwel dat de conversie een van efg en de volgende pointer een pointer naar een double (in plaats van een float) zal zijn. Het geven van twee l vlaggen is gelijk aan de L vlag.

L

Geeft aan dat ofwel de conversie een van efg en de volgende pointer een pointer naar een long double zal zijn, of dat de conversie dioux en de volgende pointer een pointer naar een long long zal zijn. (Merk op dat een long long geen ANSI C type is. Een programma dat dit gebruikt zal niet portable zijn naar alle architecturen.)

q

gelijk aan L. Deze vlag bestaat niet in ANSI C.

Bovenop deze vlaggen kan er een optionele maximum veld breedte, gegeven als een decimale integer, gegeven worden tussen de % en de conversie. Als geen breedte wordt gegeven, wordt ’oneindig’ gebruikt (met een uitzondering, zie onder); anders worden ten hoogste zoveel karakters ingelezen bij het verwerken van de conversie. Voordat de conversie begint, moet de conversie meestal witte ruimte overslaan; deze witte ruimte wordt niet geteld als veld breedte.

The volgende conversies zijn voorhanden:

%

Herkent een letterlijke ’%’. Dit betekend: ’%%’ in de format string herkent een enkel ’%’ karakter in de invoer. Geen conversie wordt uitgevoerd, en geen toewijzing aan een pointer vindt plaats.

d

Herkent een decimale integer met eventueel plus of min teken; de volgende pointer moet een pointer naar een int zijn.

D

Gelijk aan ld; deze conversie bestaat uitsluitend voor backward compatibility. (Merk op: alleen in libc4. In libc5 en glibc wordt de %D in stilte genegeerd, waardoor oudere programma’s op mysterieuze wijze de mist in gaan.)

i

Herkent een integer, eventueel met teken; de volgende pointer moet een pointer naar een int zijn. De integer wordt gelezen in een radix 16 (hexadecimaal) als het begint met ’0x’ of ’0X’, in radix 8 als het begint met ’0’ (octaal), en anders in radix 10 (decimaal). Alleen karakters die corresponderen met de radix worden gebruikt.

o

Herkent een octale integer zonder teken; de volgende pointer moet een pointer naar een unsigned int zijn.

u

Herkent een decimale integer zonder teken; de volgende pointer moet een pointer naar een unsigned int zijn.

x

Herkent een hexadecimale integer zonder teken; de volgende pointer moet een pointer naar een unsigned int zijn.

X

Gelijk aan x.

f

Herkent een drijvende komma getal met eventueel teken; de volgende pointer moet een pointer naar een float zijn.

e

Gelijk aan f.

g

Gelijk aan f.

E

Gelijk aan f.

s

Herkent een serie niet-witte-ruimte karakters; de volgende pointer moet een pointer naar een char zijn, en het array moet groot genoeg zijn om de hele serie karakters plus het NUL karakter op het einde te accepteren. De invoer string stopt als de invoer witte ruimte geeft, of als de maximum veld breedte wordt bereikt; welke van deze twee het eerst komt.

c

Herkent een aantal van breedte karakters (default 1); de volgende pointer moet een pointer naar een char zijn, en er moet genoeg ruimte zijn voor alle karakters (er wordt geen NUL karakter op het einde toegevoegd). Het normale negeren van inleidende witte ruimte wordt onderdrukt. Om witte ruimte te negeren, gebruik expliciet witte ruimte in de format string.

[

Herkent een niet lege serie karakters uit de gegeven set te accepteren karakters; de volgende pointer moet een pointer naar een char zijn, en er moet genoeg ruimte voor alle karakters in de string zijn, plus een NUL karakter. Het normale negeren van inleidende witte ruimte wordt onderdrukt. De string moet gaan bestaan uit karakters in (of niet in) een bepaalde set; de set wordt gedefinieerd door de karakters tussen het open rechte haak [ karakter en het sluitende rechte haak ] karakter. De set is exclusief die karakters als het eerste karakter na de open rechte haak een dakje ^ is. Maak om een sluitende rechte haak in de set toe te voegen, een sluitende rechte haak het eerste karakter na de open rechte haak of het dakje; iedere andere positie zal de set sluiten. Het streepje karakter - is ook speciaal; wanneer geplaats tussen twee andere karakters, zal het alle tussenliggende karakters toevoegen aan de set. Om een streepje zelf toe te voegen, maak het het laatste karakter voor de sluitende rechte haak. Bijvoorbeeld, ’[^]0-9-]’ betekend de set ’alles behalve de sluitende rechte haak, de nummers nul tot negen, en het streepje’. De string eindigt met het verschijnen van een karakter dat niet in (of, met het dakje, in) de set vertegenwoordigt is, of als de veld breedte verzadigt is.

p

Herkent een pointer waarde (zoals geprint door ’%p’ in printf(3); de volgende pointer moet een pointer naar void zijn.

n

Niets wordt verwacht; inplaats hiervan wordt het aantal karakters tot nog toe verzwolgen uit de invoer opgeslagen in de volgende pointer, deze pointer moet een pointer naar int zijn. Dit is geen conversie, alhoewel het kan worden onderdrukt met de * vlag. De C standaard zegt: ’Uitvoeren van een %n opdracht verhoogt het aantal toeschrijvingen dat de functie na uitvoering terug geeft niet’ maar het "Corrigendum" lijkt dit te weerspreken. Waarschijnlijk is het verstandig om geen aannames aan te nemen over het effect van de %n conversie op de terug geef waarde.

TERUG GEEF WAARDE

Deze functies geven het aantal toegekende invoer items terug, dit kan minder zijn dan waarin voorzien was, of zelfs nul, als een herkenning mislukte. Nul geeft weer dat, alhoewel er invoer voorhanden was, geen conversies toegekend werden; normaal gesproken is de oorzaak een foutief invoer karakter, zoals een alfabetisch karakter voor een ’%d’ conversie. De waarde EOF wordt teruggegeven als een invoer fout plaatsvond voordat een conversie plaatsvond, zoals het bereiken van end-of-file. Als een fout of end-of-file plaatsvond nadat conversie was begonnen, dan wordt het aantal succesvolle conversies terug gegeven.

ZIE OOK

getc(3), printf(3), strtod(3), strtol(3), strtoul(3)

VOLDOET AAN

De functies fscanf, scanf, en sscanf voldoen aan ANSI X3.159-1989 (’’ANSI C’’).

De q vlag is de BSD 4.4 notatie voor long long, terwijl ll of het gebruik van L een integer conversie is in de GNU notatie.

De Linux versies van deze functies zijn gebaseerd op de GNU libio bibliotheek. Bekijk de info documentatie van GNU libc (glibc-1.08) eens voor een kortere omschrijving.

BUGS

Alle functies voldoen volledig aan ANSI X3.159-1989, maar bieden de extra vlaggen q en a als ook een extra gedrag voor de L en l vlaggen. Deze laatste mag als een bug beschouwd worden, omdat het de gedragingen van vlaggen gedefinieerd in ANSI X3.159-1989 verandert.

Sommige combinaties van vlaggen gedefinieerd door ANSI C zijn niet zinnig in ANSI C (bijv. %Ld). Terwijl ze een goed gedefinieerd gedrag hebben op Linux, hoeft dit niet zo te zijn op andere architecturen. Daarom is het normaal gesproken beter om vlaggen te gebruiken die helemaal niet door ANSI C worden gedefinieerd, dat wil zeggen: gebruik q in plaats van L in combinatie met diouxX conversies, of ll.

Het gebruik van q is niet hetzelfde als op BSD 4.4, omdat het gebruikt kan worden in float conversies equivalent aan L.