Назва
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - функції форматованого вводу
Стисло
#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);
Опис
Сімейство функцій scanf зчитує ввід відповідно до формату, описаного нижче. Формат може містити вказівники перетворення; результати такого перетворення зберігаються у аргументах-покажчиках. Функція scanf читає ввід зі стандартного потоку вводу stdin, функція fscanf зчитує його з покажчика на потік stream, тоді як sscanf читає ввід з символьного ланцюжка, на який показує str.
Функція vfscanf є аналогічною ?vfprintf(3) і зчитує ввід із покажчика на потік stream, використовуючи змінний список аргументів-покажчиків (дивіться stdarg(3)). Функція vscanf сканує змінний список аргументів зі стандартного вводу, а функція vsscanf читає його з ланцюжка; вони аналогічні vprintf і vsprintf, відповідно.
Кожний наступний аргумент-покажчик повинен відповідати попередньому вказівникові перетворення (але подивіться "пригнічування" нижче). Всі перетворення вводяться зі знаком % (знак проценту). Ланцюжок формату може також містити інші знаки. Пропуски (такі як пробіл, табуляція або новий рядок) у ланцюжку формату співпадають будь-якою кількістю пропусків у вводі, включаючи жодний. Решта співпадає тільки саме з собою. Сканування припинено, якщо введений знак не співпадає з форматом, а також, коли перетворення вводу неможливо здійснити (дивіться нижче).
Перетворення
За символом % можуть слідувати наступні знаки, як вказівники перетворення:
: Скасовує присвоєння нового значення покажчику. Наступне перетворення відбудеться як звичайно, але без використання покажчика; результат перетворення просто вивільняється.
a : (glibc) Вказує, що перетворення буде таким самим, що й у випадку s, необхідну для ланцюжка пам'ять буде відведено за допомогою malloc і покажчик на неї присвоєно покажчиковій змінній типу char, яку не потрібно попередньо ініціювати. Цей прапорець не існує в ANSI C (C89) і має відмінне значення в C99.
a : (C99) Рівнозначний f.
h : Вказує на те, що перетворення буде одним з dioux або n і, що наступний покажчик вказує на short int (замість int).
l : Вказує на те, що перетворення буде одним з dioux або n і, що наступний покажчик вказує на long int (замість int) або, що перетворення буде одним з efg і наступний покажчик вказує на double (замість float). Вказування двох прапорців l рівнозначне прапорцю L.
L : Вказує на те, що перетворення буде або одним з efg і наступний покажчик вказує на long double, або перетворення буде одним з dioux і наступний покажчик вказує на long long. (Зауважте, що long long не є типом, що відповідає ANSI C. Програми, що використовують його не будуть портабельними на різноманітні архітектури.)
q : Рівнозначний L. Цього прапорця не існує в ANSI C.
До цих прапорців можна також додати вказівник максимальної ширини поля у вигляді десяткового цілого, розміщений між % і перетворенням. Якщо ширину не задано, вона буде необмеженою (з одним виключенням, описаним нижче), у протилежному випадку, щонайбільше вказане число знаків зчитуються при перетворенні. Перед початком перетворень пропускаються пробіли, вони не зараховуються до ширини поля.
Наявні наступні перетворення:
%
: Співпадає з буквальним %'. Тобто,%%' у ланцюжку формату співпадає з єдиним `%' у вводі. Власне перетворення не відбувається, так само як і присвоєння.
d : Співпадає з десятковим цілим із можливим знаком; наступний покажчик повинен бути типу int.
D : Рівнозначний ld; існує лише для оберненої сумісності. (Примітка: це тільки в libc4. В libc5 і glibc, %D мовчки ігнорується, спричиняючи загадкову відмову від роботи старих програм.)
i
: Співпадає з цілим з можливим знаком; наступний покажчик повинен бути типу int. Ціле буде прочитано у шістнадцятковій системі числення, якщо воно починається з 0x' або0X' і у вісімковій, якщо з `0', у протилежному випадку - у десятковій.
o : Співпадає з беззнаковим вісімковим цілим; наступний покажчик повинен вказувати на unsigned int.
u : Співпадає з беззнаковим десятковим цілим; наступний покажчик повинен вказувати на unsigned int.
x : Співпадає з беззнаковим шістнадцятковим цілим; наступний покажчик повинен вказувати на unsigned int.
X : Еквівалентний X.
f : Співпадає з числом з плаваючою точкою з можливим знаком; відповідний аргумент повинен бути типу float.
e : Еквівалентний f.
g : Еквівалентний f.
E : Еквівалентний f.
s : Співпадає з послідовністю знаків не-пробілів; відповідний аргумент повинен бути типу char, і масив повинен бути додатньо великим, щоб вмістити всю послідовність і кінцевий NULL-символ. Зчитування ввідного ланцюжка припиниться при першому ж пропуску або ж досягненні максимальної ширини поля.
c : Співпаде з послідовністю вказаної кількості знаків (за замовчуванням 1); відповідний аргумент повинен бути покажчиком типу char, і мати достатньо місця, щоб вмістити всі знаки (кінцевий NULL не додається). Звичний пропуск пробілу не відбувається. Щоб пропустити передуючий пробіл, додайте явний пробіл до ланцюжка формату.
[ : Співпадає з послідовністю знаків зі вказаного всередині квадратних дужок набору дозволених; відповідний аргумент повинен бути покажчиком типу char, і мати додстатньо місця для всіх знаків ланцюжка з кінцевим NULL-символом. Звичний пропуск пробілу не відбувається. Ланцюжок складатиметься зі знаків, включених в (або виключених з) певний набор знаків; набір означено знаками між відкриваючою [ і закриваючою ]. Набір виключатиме ці знаки, якщо першим в наборі стоїть ^ . Щоб включити квадратну дужку в набір, зробіть її першим знаком за відкриваючою квадратною дужкою або ^; будь-яка інша позиція завершить набір. Знак риски - також спеціальний; якщо добавити його між двома іншими знаками, це додає всі проміжні знаки (набору ASCII). Щоб включити буквальну риску, зробіть її останнім знаком перед закриваючою квадратною дужкою. Наприклад, "[^]0-9-]" означає "все, окрім правої квадратної дужки, чисел від нуля до дев'яти і риски". Зчитування ланцюжка завершиться як тільки буде знайдено знак, що не належить наборові (або у випадку ^, навпаки, належить) або ж коли досягнуто максимальної ширини поля.
p : Співпадає з покажчиковим значенням (як виводиться "%p" у printf(3)); відповідний аргумент повинен бути покажчиком на void.
n : Нічого не очікується, натомість кількість прочитаних знаків вводу буде збережено у відповідному аргументові, який повинен бути покажчиком типу int. Це не являється перетворенням, хоча його можна блокувати прапорцем *****. Стандарт C каже, що "виконання %n не приростає відлік символів по завершенню виконання", але Поправка (Corrigendum), схоже суперечить цьому. Напевне, розсудливішим буде не робити якихось припущень щодо ефекту перетворень %n.
Повернені значення
Ці функції повертають кількість присвоєних елементів, що може виявитись меншим ніж вказано прочитати, або навіть жодного у випадку неспівпадання. Нуль означає, що навіть при присутності ввідних даних, жодного перетворення не було присвоєно; типово це відбувається через недійсний введений символ, скажімо літера алфавіту для перетворення "%d". EOF повертається, якщо невдача вводу мала місце до того, як відбулась якась проба перетворення, як скажімо при досягненні кінця файлу. Якщо перетворення відбулося до того, як виникла помилка або досягнуто кінця файлу, повертається число успішних перетворень.
Відповідність стандартам
Функції fscanf, scanf і sscanf відповідають ANSI X3.159-1989 ("ANSI C").
Прапорець q - це нотація BSD 4.4 для типу long long, тоді як ll або використання літери L в перетвореннях цілих - це нотація GNU.
Лінукс-версія цих функцій основано на бібліотеці libio GNU. Загляніть до info-документації libc GNU (glibc-1.08) для точнішого опису.
Вади
Всі функції повністю узгоджуються з ANSI X3.159-1989, але надають додаткові прапорці q так само як додаткове поводження прапорців L і l. Останнє може вважатися вадою, оскільки це змінює поводження прапорців, визначених стандартом ANSI X3.159-1989.
Деякі прапорці, означені ANSI C не мають змісту в самому ANSI C (наприклад %Ld), зате добре визначене поводження в Лінуксі, але не на всіх архітектурах. Тому іноді краще використовувати прапорці, не визначені ANSI C, тобто q замість L у комбінації з перетвореннями diouxX або ll.
Використання q не співпадає з відповідним у BSD 4.4, так як цей прапорець можна застосувати для перетворення чисел з плаваючою точкою тотожно L.