SCANF(3S)

НАЗВАНИЕ
scanf, fscanf, sscanf - ввод с преобразованием по формату

СИНТАКСИС


	include <stdio.h>

	

	nt scanf (format [, pointer] ...)

	har *format;

	

	nt fscanf (stream, format [, pointer] ...)

	ILE *stream;

	har *format;

	

	nt sscanf (s, format [, pointer] ...)

	har *s, *format;

ОПИСАНИЕ
Функция scanf читает данные из стандартного потока ввода stdin. Функция fscanf читает данные из потока ввода, заданного аргументом stream. Функция sscanf читает цепочку символов с адресом s. Каждая из перечисленных функций вводит символы, интерпретирует их в соответствии с форматом и записывает по указанным адресам. Аргументами функций являются: format - формат, управляющий преобразованием, и pointers - указатели на области памяти, куда следует помещать результаты преобразований. Если для заданного формата не хватает указателей, результат непредсказуем; если же указателей слишком много, лишние просто игнорируются.

Формат обычно содержит спецификаторы преобразований, которые задают способ интерпретации вводимых данных. В формате могут содержаться:

Пробельные символы (собственно пробел, табуляция, перевод строки, переход к новой странице), которые (за исключением двух описанных ниже случаев) вызывают чтение до следующего непробельного символа.
Обычный символ (не %), который должен совпадать со следующим символом потока ввода.
Спецификаторы преобразований, состоящие из символа %, необязательного символа подавления присваивания *, необязательного числа, задающего максимальную ширину поля в потоке ввода, необязательного символа l или h, указывающего размер переменной, получающей значение, а также кода преобразования.

Спецификатор задает способ преобразования текущего входного поля; результат присваивается переменной, на которую указывает соответствующий аргумент pointer, если не задано подавление присваивания. Подавление присваивания позволяет пропускать в потоке ввода отдельные поля. Поле в потоке ввода определяется как последовательность символов, не содержащая пробелов, которая либо ограничивается "неуместным" (в данном контексте) символом, либо определяется шириной, если она задана. Для всех преобразований, кроме [ и c, пробелы в начале поля игнорируются.

Код преобразования определяет способ интерпретации входного поля; соответствующий аргумент-указатель, как правило, должен иметь соответствующий тип. Для пропускаемых полей указатель не задается. Распознаются следующие коды преобразований:

% Из потока ввода должен быть прочитан единственный символ %; никаких присваиваний не выполняется.
d Из потока ввода должно быть прочитано целое десятичное число; соответствующий аргумент должен быть указателем на целое.
u Из потока ввода должно быть прочитано целое десятичное без знака; соответствующий аргумент должен быть указателем на целое без знака.
o Из потока ввода должно быть прочитано целое восьмеричное число; соответствующий аргумент должен быть указателем на целое.
x Из потока ввода должно быть прочитано целое шестнадцатеричное число; соответствующий аргумент должен быть указателем на целое.
i Из потока ввода должно быть прочитано целое число; соответствующий аргумент должен быть указателем на целое. Значение числа вычисляется в соответствии с соглашениями языка C: префикс 0 обозначает восьмеричное число, префикс 0x - шестнадцатеричное, отсутствие префикса - десятичное.
n Общее количество символов (включая пробельные), прочитанных с начала выполнения функции, запоминается в очередной переменной из списка аргументов. Из потока ввода ничего не читается.
e, f, g Из потока ввода должно быть прочитано число с плавающей точкой; оно представляет собой последовательность цифр с необязательным знаком, необязательной десятичной точкой и необязательным порядком; порядок обозначается буквой e или E, за которой может следовать +, - или пробел, а затем - целое число. Соответствующий аргумент должен быть указателем на переменную типа float.
s Из потока ввода должна быть прочитана цепочка символов; соответствующий аргумент должен быть указателем на символьный массив достаточной длины, чтобы в нем поместились вводимые данные с завершающим пустым символом \0, который добавляется автоматически. Признак конца входного поля - пробельный символ.
c Из потока ввода должен быть прочитан единственный символ; соответствующий аргумент должен быть указателем на символ. Обычный пропуск пробельных символов в этом случае не производится; для чтения ближайшего непробельного символа нужно задать спецификатор %1s. Если задана ширина поля, то соответствующий аргумент должен указывать на символьный массив; в этом случае вводится заданное количество символов.
[ Входные данные обрабатываются особым образом. За открывающей скобкой следует ряд символов, которые называются шаблоном сканирования, а затем закрывающая скобка; входное поле представляет собой максимальный участок потока ввода, состоящий исключительно из символов шаблона. Если первым символом шаблона является ^, это означает, что входное поле представляет собой максимальный участок потока ввода, содержащий любые символы кроме перечисленных в шаблоне. Шаблон сканирования записывается по определенным правилам. Несколько символов можно задать конструкцией первый-последний; таким образом, ряд [0123456789] можно изобразить как [0-9]. При использовании этого правила первый должен быть лексикографически меньше или равен последнему, иначе минус рассматривается как обычный символ шаблона. Минус рассматривается как обычный символ, если он находится на первом или на последнем месте в шаблоне. Если в шаблон нужно включить закрывающую скобку, то она должна быть самым первым символом шаблона (возможно, с предшествующим ^), в противном случае она рассматривается как ограничитель шаблона. Соответствующий этому спецификатору аргумент должен быть указателем на символьный массив достаточной длины, способный вместить читаемые данные вместе с ограничителем \0, добавляемым автоматически. Это преобразование считается завершившимся успешно, если из потока ввода выбран хотя бы один символ, соответствующий шаблону.

%	Из потока ввода должен быть прочитан единственный символ %; никаких присваиваний не выполняется.
d	Из потока ввода должно быть прочитано целое десятичное число; соответствующий аргумент должен быть указателем на целое.
u	Из потока ввода должно быть прочитано целое десятичное без знака; соответствующий аргумент должен быть указателем на целое без знака.
o	Из потока ввода должно быть прочитано целое восьмеричное число; соответствующий аргумент должен быть указателем на целое.
x	Из потока ввода должно быть прочитано целое шестнадцатеричное число; соответствующий аргумент должен быть указателем на целое.
i	Из потока ввода должно быть прочитано целое число; соответствующий аргумент должен быть указателем на целое. Значение числа вычисляется в соответствии с соглашениями языка C: префикс 0 обозначает восьмеричное число, префикс 0x - шестнадцатеричное, отсутствие префикса - десятичное.
n	Общее количество символов (включая пробельные), прочитанных с начала выполнения функции, запоминается в очередной переменной из списка аргументов. Из потока ввода ничего не читается.
e, f, g	Из потока ввода должно быть прочитано число с плавающей точкой; оно представляет собой последовательность цифр с необязательным знаком, необязательной десятичной точкой и необязательным порядком; порядок обозначается буквой e или E, за которой может следовать +, - или пробел, а затем - целое число. Соответствующий аргумент должен быть указателем на переменную типа float.
s	Из потока ввода должна быть прочитана цепочка символов; соответствующий аргумент должен быть указателем на символьный массив достаточной длины, чтобы в нем поместились вводимые данные с завершающим пустым символом \0, который добавляется автоматически. Признак конца входного поля - пробельный символ.
c	Из потока ввода должен быть прочитан единственный символ; соответствующий аргумент должен быть указателем на символ. Обычный пропуск пробельных символов в этом случае не производится; для чтения ближайшего непробельного символа нужно задать спецификатор %1s. Если задана ширина поля, то соответствующий аргумент должен указывать на символьный массив; в этом случае вводится заданное количество символов.
[	Входные данные обрабатываются особым образом. За открывающей скобкой следует ряд символов, которые называются шаблоном сканирования, а затем закрывающая скобка; входное поле представляет собой максимальный участок потока ввода, состоящий исключительно из символов шаблона. Если первым символом шаблона является ^, это означает, что входное поле представляет собой максимальный участок потока ввода, содержащий любые символы кроме перечисленных в шаблоне. Шаблон сканирования записывается по определенным правилам. Несколько символов можно задать конструкцией первый-последний; таким образом, ряд [0123456789] можно изобразить как [0-9]. При использовании этого правила первый должен быть лексикографически меньше или равен последнему, иначе минус рассматривается как обычный символ шаблона. Минус рассматривается как обычный символ, если он находится на первом или на последнем месте в шаблоне. Если в шаблон нужно включить закрывающую скобку, то она должна быть самым первым символом шаблона (возможно, с предшествующим ^), в противном случае она рассматривается как ограничитель шаблона. Соответствующий этому спецификатору аргумент должен быть указателем на символьный массив достаточной длины, способный вместить читаемые данные вместе с ограничителем \0, добавляемым автоматически. Это преобразование считается завершившимся успешно, если из потока ввода выбран хотя бы один символ, соответствующий шаблону.

Кодам преобразований d, u, o, x, i может предшествовать символ l или h, означающий, что соответствующий аргумент указывает на переменную типа long или short, а не int. Аналогично, кодам e, f, g может предшествовать символ l, означающий, что соответствующий аргумент указывает на переменную типа double, а не float. Для остальных кодов преобразований модификаторы l и h игнорируются.

Функция scanf завершается по концу файла, при исчерпании формата или при обнаружении в потоке ввода символа, противоречащего формату. В последнем случае символ-нарушитель остается непрочитанным в потоке ввода.

Функция scanf возвращает число успешно введенных и преобразованных величин; это число может оказаться нулем, если слишком рано обнаружилось несоответствие с форматом. Если ввод закончился без конфликтов и преобразований, результат равен EOF.

ПРИМЕРЫ

В результате вызова
```
	nt  n;  float x;  char name[50];

	 = scanf("%d%f%s", &i, &x, name);
```
при наличии во входном потоке символов
```
	5 54.32E-1 Bill
```
будет присвоено: переменной n - значение 3, переменной i - значение 25, переменной x - значение 5.432, а в массив name будет занесено Bill\0.
После вызова
```
	nt  i,j;  float x;  char name[50];

	void)scanf("%i%2d%f%*d %[0-9]", &j, &i, &x,name);
```
при наличии во входном потоке символов
```
	11 56789 0123 56a72
```
будет присвоено: переменной j - значение 9, переменной i - значение 56, переменной x - значение 789., последовательность 0123 будет пропущена, а в массив name будет занесено 56\0. Если после этого вызова последует вызов getchar [см. getc(3S)], то будет прочитан символ a.
В результате вызова
```
	nt i, j, s, e;  char name[50];

	void)scanf("%i %i %n%s%n", &i, &j, &s, name, &e);
```
при наличии во входном потоке
```
	x11 0xy johnson
```
будет присвоено: переменной i - значение 17, переменной j - значение 0, переменной s - значение 6, в массив name будет занесено xy\0, а переменной e присвоено значение 8. Таким образом, длина заполненной части массива name равна e - s = 2. При следующим за этим вызове getchar [см. getc(3S)] будет прочитан пробел.

СМ. ТАКЖЕ
getc(3S), printf(3S), stdio(3S), strtod(3C), strtol(3C).

ДИАГНОСТИКА
Описанные функции возвращают значение EOF при исчерпании потока ввода, или число успешно введенных и преобразованных величин.

СЮРПРИЗЫ
Заключительные пробельные символы (включая перевод строки) остаются в потоке ввода непрочитанными, если только они не были явно затребованы форматом.