C/scanf

Deklaracja

W pliku nagłówkowym stdio.h:

int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *str, const char *format, ...);

W pliku nagłówkowym 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);

Opis

Funkcje odczytują dane zgodnie z podanym formatem opisanym niżej. Funkcje scanf i vscanf odczytują dane ze standardowego wejścia (tj. stdin); fscanf i vfscanf ze strumienia podanego jako argument; a sscanf i vsscanf z podanego ciągu znaków.

Funkcje vscanf, vfscanf i vsscanf różnią się od odpowiadających im funkcjom scanf, fscanf i sscanf tym, że zamiast zmiennej liczby argumentów przyjmują argument typu va_list.

Argumenty

format: format odczytu danych
stream: strumień wejściowy, z którego mają być odczytane dane
str: tablica znaków, z której mają być odczytane dane
ap: wskaźnik na pierwszy argument z listy zmiennej liczby argumentów

Format

Format składa się ze zwykłych znaków (innych niż znak '%') oraz sekwencji sterujących, zaczynających się od symbolu procenta, po którym następuje:

opcjonalna gwiazdka,
opcjonalne maksymalna szerokość pola,
opcjonalne określenie rozmiaru argumentu,
określenie formatu.

Jeżeli po znaku procenta występuje od razu drugi procent to cała sekwencja traktowana jest jak zwykły znak procenta (tzn. jest on wypisywany na wyjście).

Wystąpienie w formacie białego znaku powoduje, że funkcje z rodziny scanf będą odczytywać i odrzucać znaki, aż do napotkania pierwszego znaku nie będącego białym znakiem.

Wszystkie inne znaki (tj. nie białe znaki oraz nie sekwencje sterujące) muszą dokładnie pasować do danych wejściowych.

Wszystkie białe znaki z wejścia są ignorowane, chyba że sekwencja sterująca określa format [, c lub n.

Jeżeli w sekwencji sterującej występuje gwiazdka to dane z wejścia zostaną pobrane zgodnie z formatem, ale wynik konwersji nie zostanie nigdzie zapisany. W ten sposób można pomijać część danych.

Maksymalna szerokość pola przyjmuje postać dodatniej liczby całkowitej zaczynającej się od cyfry różnej od zera. Określa ona ile maksymalnie znaków dany format może odczytać. Jest to szczególnie przydatne przy odczytywaniu ciągu znaków, gdyż dzięki temu można podać wielkość tablicy (minus jeden) i tym samym uniknąć błędów przepełnienia bufora.

Rozmiar argumentu

Dla formatów d, i, o, u, x i n można użyć jednego z modyfikatorów rozmiaru:

hh - oznacza, że format odnosi się do argumentu typu wskaźnik na signed char lub unsigned char,
h - oznacza, że format odnosi się do argumentu typu wskaźnik na short lub wskaźnik na unsigned short,
l (el) - oznacza, że format odnosi się do argumentu typu wskaźnik na long lub wskaźnik na unsigned long,
ll (el el) - oznacza, że format odnosi się do argumentu typu wskaźnik na long long lub wskaźnik na unsigned long long,
j - oznacza, że format odnosi się do argumentu typu wskaźnik na intmax_t lub wskaźnik na uintmax_t,
z - oznacza, że format odnosi się do argumentu typu wskaźnik na size_t lub odpowiedni typ ze znakiem,
t - oznacza, że format odnosi się do argumentu typu wskaźnik na ptrdiff_t lub odpowiedni typ bez znaku.

Dla formatów a, e, f i g można użyć modyfikatorów rozmiaru

l, który oznacza, że format odnosi się do argumentu typu wskaźnik na double lub
L, który oznacza, że format odnosi się do argumentu typu wskaźnik na long double.

Dla formatów c, s i [ modyfikator l oznacza, że format odnosi się do argumentu typu wskaźnik na wchar_t.

Format

Funkcje z rodziny scanf obsługują następujące formaty:

d, i odczytuje liczbę całkowitą, której format jest taki sam jak oczekiwany format przy wywołaniu funkcji strtol z argumentem base równym odpowiednio 10 dla d lub 0 dla i, argument powinien być wskaźnikiem na int;

o, u, x odczytuje liczbę całkowitą, której format jest taki sam jak oczekiwany format przy wywołaniu funkcji strtoul z argumentem base równym odpowiednio 8 dla o, 10 dla u lub 16 dla x, argument powinien być wskaźnikiem na unsigned int;

a, e, f, g odczytuje liczbę rzeczywistą, nieskończoność lub NaN, których format jest taki sam jak oczekiwany przy wywołaniu funkcji strtod, argument powinien być wskaźnikiem na float;

c odczytuje dokładnie tyle znaków ile określono w maksymalnym rozmiarze pola (domyślnie 1), argument powinien być wskaźnikiem na char;

s odczytuje sekwencje znaków nie będących białymi znakami, argument powinien być wskaźnikiem na char;

[ odczytuje niepusty ciąg znaków, z których każdy musi należeć do określonego zbioru, argument powinien być wskaźnikiem na char;

p odczytuje sekwencje znaków zależną od implementacji odpowiadającą ciągowi wypisywanemu przez funkcję printf, gdy podano sekwencję %p, argument powinien być typu wskaźnik na wskaźnik na void;

n nie odczytuje żadnych znaków, ale zamiast tego zapisuje do podanej zmiennej liczbę odczytanych do tej pory znaków, argument powinien być typu wskaźnik na int.

Słówko więcej o formacie [. Po otwierającym nawiasie następuje ciąg określający znaki jakie mogą występować w odczytanym napisie i kończy się on nawiasem zamykającym tj. ]. Znaki pomiędzy nawiasami (tzw. scanlist) określają możliwe znaki, chyba że pierwszym znakiem jest ^ - wówczas w odczytanym ciągu znaków mogą występować znaki nie występujące w scanlist. Jeżeli sekwencja zaczyna się od [] lub [^] to ten pierwszy nawias zamykający nie jest traktowany jako koniec sekwencji tylko jak zwykły znak. Jeżeli wewnątrz sekwencji występuje znak - (minus), który nie jest pierwszym lub drugim jeżeli pierwszym jest ^ ani ostatnim znakiem zachowanie jest zależne od implementacji.

Formaty A, E, F, G i X są również dopuszczalne i mają takie same działanie jak a, e, f, g i x.

Wartość zwracana

Funkcja zwraca EOF jeżeli nastąpi koniec danych lub błąd odczytu zanim jakiekolwiek konwersje zostaną dokonane lub liczbę poprawnie wczytanych pól (która może być równa zero).

Przykładowe wywołanie służące do pobrania tylko i wyłącznie znaków: - (myślnik), ' (apostrof), (spacja) oraz małych i wielkich liter:

scanf(" %[-' A-Z,a-z]s",&zmienna);

Zobacz też

printf, gets

Podstawowe procedury wejścia i wyjścia