Fscanf что возвращает
Функция vfscanf является аналогом vfprintf (3) и читает информацию из потока, на который указывает stream , используя список указателей (см. stdarg (3)). Функция vscanf считывает список переменных аргументов из стандартного ввода, а функция vsscanf считывает его из строки. Эти функции являются аналогами функций vprintf и vsprintf соответственно.
Каждый последующий указатель на аргумент должен полностью соответствовать определителю преобразования (однако, обратите внимание на знак отключения ("supressor"), описанный ниже). Все определители обозначены символом % (знаком процента). Строка format может также содержать другие символы. Пустые символы (такие, как пробел, табуляция или перевод строки) в строке format соответствуют любому количеству пустых символов (даже нулю) в строке ввода. Все остальные символы соответствуют только сами себе. Считывание прекращается, когда вводимый символ не соответствует форматному символу. Считывание также прекращается, если преобразование входящих данных не может быть произведено (см. ниже).
ПРЕОБРАЗОВАНИЯ
Дополнением к этим флагам может быть необязательная максимальная ширина поля, выраженная целым десятичным числом и расположенная между знаком % и преобразованием. Если ширина не указана, по умолчанию используется "бесконечность"; в противном случае соответствующее количество символов считывается в процессе преобразования. До начала преобразования большинство преобразователей пропускают пробелы; эти пробелы не учитываются при определении ширины поля.
Существуют следующие преобразователи: % (определяет символ `%’. То есть `%%’ в форматной строке соответствует символу `%’ на входе); 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 (соответствует последовательности из width символов (по умолчанию 1); далее следует указатель на char ; для вмещения всех символов (к ним не добавляется завершающий NULL ) должно быть достаточно места. Обычный пропуск начальных "пустых" символов отключен, поэтому для пропуска "пустых" символов в начале используйте явный пробел в формате.); [ (определяет "непустую" последовательность из определенного набора принятых символов; далее следует указатель на char ; для вмещения всех символов, включая завершающий NULL , должно быть достаточно места. Обычный пропуск начальных пустых символов отключен. Строка должна быть из символов в конкретном наборе или не в наборе; набор определяется символами между скобками [ и ] . Множество исключает из себя символы, если сразу после открывающейся скобки стоит символ ^ (циркумфлекс). Чтобы включить закрывающую скобку в набор, поставьте ее сразу после открывающей скобки или циркумфлекса; в любой другой позиции закрывающая скобка будет обозначать конец набора. Символ дефиса ( — ) также является специальным; когда он расположен между двумя другими символами, он добавляет все промежуточные символы к набору. Чтобы включить дефис в набор, поставьте его на последнее место перед закрывающей скобкой. Например, `[^]0-9-]’ означает набор `все символы, кроме закрывающей скобки, кроме чисел от нуля до 9-и и кроме дефиса’. Строка заканчивается либо при появлением символа, не включенного (или если с циркумфлексом, то включенного) в набор, либо при достижении максимальной ширины поля.); p (соответствует значению указателя в формате `%p’ для printf (3); далее должен следовать указатель на void ); n (ничего не ожидается; вместо этого символы, принятые до этого момента с ввода, сохраняются с помощью последующего указателя на int ). Это не преобразование, хотя оно также может быть "подавлено" при использовании флага * . В стандарте C сказано: `Использование директивы %n не увеличивает показания счетчика назначения, возвращаемые при завершении работы’,- но, видимо, это большая ошибка.
ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
СМ. ТАКЖЕ
СООТВЕТСТВИЕ СТАНДАРТАМ
Флаг q указывается BSD 4.4 для long long , а флаги ll или L с преобразованиями чисел указываются в GNU
Версия этих функций в Linux основана на GNU -библиотеке libio . Более краткое описание можно найти в info -документации GNU libc (glibc-1.08).
НАЙДЕННЫЕ ОШИБКИ
Некоторые комбинации флагов, определенные в ANSI C , не имеют смысла даже для этого стандарта (например, %Ld ). Они могут иметь вполне определенное поведение в Linux, но это не значит, что они будут вести себя так же и в других системах. Поэтому лучше использовать флаги, не определенные в ANSI C , т.е. использовать q вместо L в комбинации с преобразованиями diouxX или ll .
Использование q в системе BSD 4.4 не похоже на описанное ранее, поскольку данный флаг может быть использован при изменяемых преобразованиях аналогично L .
Fscanf что возвращает
scanf, 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);
Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):
vscanf(), vsscanf(), vfscanf():
_XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
или cc -std=c99
ОПИСАНИЕ
Если количество определителей преобразования в format превышает количество параметров указателей, то результат не определён. Если количество параметров указателей превышает количество определителей преобразования, то лишние параметры указатели вычисляются, но игнорируются.
Функция scanf() считывает информацию из стандартного потока ввода stdin; fscanf() считывает информацию из потока, на который указывает stream, а sscanf() считывает информацию из символьной строки, на которую указывает str.
Функция vfscanf() является аналогом vfprintf(3) и читает информацию из потока, на который указывает указатель stream, используя список указателей переменной длины (смотрите stdarg(3)). Функция vscanf() считывает список параметров переменной длины из стандартного ввода, а функция vsscanf() считывает его из строки. Эти функции являются аналогами функций vprintf(3) и vsprintf(3), соответственно.
Строка format состоит из последовательности инструкций (directives), которые описывают порядок обработки входных символов. Если обработка инструкции завершается с ошибкой, то чтение прекращается и scanf() завершает работу. «Отказом» может быть: ошибка ввода, то есть недоступность входных символов или ошибка совпадения, то есть получены неподходящие данные (смотрите далее).
Инструкцией может быть:
- Последовательность пробельных символов (пробел, табуляция, символ новой строки и т. д.; смотрите isspace(3)). Эта инструкция совпадает с любым количеством пустого места, включая отсутствие данных.
- Обычный символ (т. е., отличный от пробельного или «%»). Такой символ должен точно совпадать со следующим символом входных данных.
- Определитель преобразования, который начинается с символа «%» (процент). Последовательность символов ввода преобразуется в соответствии с определителем, а результат помещается в соответствующий параметр указатель. Если следующий элемент ввода не соответствует определителю преобразования, то преобразование завершается с ошибкой — ошибкой совпадения.
Каждый определитель преобразования в format начинается с символа «%» или последовательности символов «%n$» (смотрите о разнице далее) за которым следует:
- Необязательный символ подавления назначения «*»: scanf() читает данные как предписано определителем преобразования, но отбрасывает их. Соответствующий параметр указатель необязателен, и этот определитель не учитывается в счётчике успешных назначений, возвращаемом scanf().
- Необязательный символ «m». Используется в строковых преобразованиях (%s, %c, %[) и освобождает вызывающего от необходимости выделять соответствующий буфер для хранения входных данных: вместо этого scanf() выделяет буфер достаточного размера и присваивает адрес этого буфера соответствующему параметру указателю, который должен быть указателем на переменную char * (эту переменную не нужно инициализировать перед вызовом). Вызывающий должен вызвать free(3) для этого буфера, как только он станет ненужным.
- Необязательное целое десятичное число, которое задаёт максимальную ширину поля. Чтение символов прерывается по достижении этого максимума или при нахождении несовпадающего символа, неважно что случится раньше. В большинстве преобразований начальные пробельные символы отбрасываются (исключения приведены далее), и эти отброшенные символы не учитываются в максимальной ширине поля. В преобразованных строках ввода сохраняется конечный байт null (‘\0’) для отметки конца ввода; в максимальной ширине поля он также не учитывается.
- Необязательный символ модификатора типа. Например, модификатор типа l используется в преобразованиях целых чисел, например с помощью %d, для указания того, что соответствующий параметр указатель ссылается на long int, а не на int.
- Определитель преобразования, который задаёт тип входного преобразования.
Определители преобразования в format бывают двух видов: начинающиеся с «%» и начинающиеся с «%n$». Эти два вида не должны использоваться одновременно в строке format, за исключением случая, когда строка, содержащая определители «%n$», может включать %% и %*. Если в format содержатся определители «%», то они задаются в порядке появления параметров указателей, указанных после. В форме «%n$» (есть в POSIX.1-2001, но отсутствует в C99), n — это десятичное целое, которое задаёт в какое место должен быть помещён ввод, то есть указывает на расположение n-го параметра указателя, передаваемого после format.
Преобразования
Доступны следующие определители преобразования:
% Совпадает с литерой «%». То есть %% в строке формата соответствует одиночному символу данных «%». Преобразование не выполняется (но начальные пробельные символы отбрасываются) и назначения не происходит. 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. a (C99) Эквивалентно f. s Совпадает с последовательностью непробельных символов; следующий указатель должен указывать на первый элемент массива символов достаточной длины для сохранения входной последовательности и завершающего байта null (‘\0’), который добавляется автоматически. Входная строка обрывается при появлении пробельного символа или достижении максимальной ширины поля, неважно что случится раньше. c Совпадает с последовательностью символов, чья длина задаётся максимальной шириной поля (по умолчанию 1); следующий указатель должен быть указателем на char, и должно быть достаточно места для всех символов (завершающий байт null не добавляется). Обычный пропуск начальных пробелов не выполняется. Чтобы пропустить пробелы, явно укажите их в формате. [ Совпадает с непустой последовательностью символов из задаваемого набора допустимых символов; следующий указатель должен быть указателем на char и должно быть достаточно места для всех символов в строке плюс завершающий байт null. Обычный пропуск начальных пробелов не выполняется. Строка будет состоять (или нет) из символов определённого набора; набор задаётся указанием символов между символом открывающей скобки [ и закрывающей скобки ]. Набором определяются исключающиеся символы, если первым символом после открывающей скобки является символ диакритического знака (^). Чтобы включить закрывающую скобку в набор, укажите её первым символом после открывающей скобки или диакритического знака; в любой другой позиции она закрывает набор. Символ переноса — также является специализированным; если он указывается между двумя символами, то в набор добавляются все лежащие в промежутке символы. Чтобы добавить в набор символ переноса укажите его последним, перед конечной закрывающей скобкой. Например, [^]0-9-] означает, что «все символы, кроме закрывающей скобки, цифр от 0 до 9 и переноса». Строка обрывается при появлении символа не из набора (или, при указании символа диакритического знака, из) или при достижении ширины поля. p Совпадает со значением указателя (как выводится при %p в printf(3)); следующий указатель должен быть указателем на void. n Ничего не ожидается; вместо этого количество символов, использованных к настоящему времени из ввода, сохраняется по следующему указателю, который должен быть указателем на int. Это не преобразование и не увеличивает счётчик, возвращаемый функцией. Назначение может подавляться при указании символа подавления назначения *, но влияние этого на возвращаемое значение не определено. Поэтому преобразования %*n лучше не использовать.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Если конец входных данных был достигнут раньше, чем произошло хотя бы одно совпадение или при ошибке совпадения возвращается значение EOF. Значение EOF также возвращается при ошибке чтения; в этом случае для потока устанавливается индикатор ошибки (смотрите ferror(3)), а в errno указывается номер ошибки.
ОШИБКИ
АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
| Интерфейс | Атрибут | Значение |
| scanf(), fscanf(), sscanf(), vscanf(), vsscanf(), vfscanf() |
безвредность в нитях | безвредно (MT-Safe locale) |
СООТВЕТСТВИЕ СТАНДАРТАМ
Определитель q в 4.4BSD используется для long long, а определители ll или L используются в GNU для преобразования целых чисел.
Версия Linux этих функций основана на библиотеке GNU libio. Более точное описание функций можно найти в документации в формате info на GNU libc (glibc-1.08).
ЗАМЕЧАНИЯ
Модификатор выделения-назначения «a»
Использование буквы a для этой цели проблематично, так как a также используется в стандарте ISO C как синоним f (ввод данных с плавающей запятой). В POSIX.1-2008 для назначения с выделением определён модификатор m (смотрите в ОПИСАНИЕ выше).
Заметим, что модификатор a недоступен, если программа скомпилирована посредством gcc -std=c99 или gcc -D_ISOC99_SOURCE (если не определён _GNU_SOURCE); в этом случае a рассматривается как определитель чисел с плавающей запятой (смотрите выше).
Поддержка модификатора m была добавлена в glibc начиная с версии 2.7, и в новых программах нужно использовать этот модификатор вместо a.
Стандартизированный в POSIX модификатор m имеет дополнительные преимущества над a:
* Он может также применяться к определителям преобразования %c (например, %3mc). * Исчезает неоднозначность с определителем преобразования чисел с плавающей запятой %a (не подвержен влиянию gcc -std=c99).
ДЕФЕКТЫ
Некоторые комбинации модификаторов типов и определителей преобразования, определённые в ANSI C, не имеют смысла (например, %Ld). Хотя они могут иметь хорошо описанное поведение в Linux, это не обязательно так на других архитектурах. Поэтому, обычно, лучше использовать модификаторы, не определённые в ANSI C, то есть использовать q вместо L в комбинации с преобразованием d, i, o, u, x и X или ll.
Работа q отличается от работы в 4.4BSD, так как может использоваться при преобразовании вещественных числе подобно L.
ПРИМЕР
Как показано в примере выше, необходимо вызывать free(3) только, если при вызове scanf() была прочитана строка.
fscanf , _fscanf_l , fwscanf , _fwscanf_l
Считывают форматированные данные из потока. Доступны более безопасные версии этих функций; см. раздел fscanf_s , _fscanf_s_l fwscanf_s ,, _fwscanf_s_l .
Синтаксис
Параметры
stream
Указатель на структуру FILE .
format
Строка управления форматом.
argument
Необязательные аргументы.
locale
Используемый языковой стандарт.
Возвращаемое значение
Каждая из этих функций возвращает число успешно преобразованных и назначенных полей. Возвращаемое значение не включает поля, которые были считаны, но не были назначены. Возвращаемое значение 0 указывает, что поля не были назначены. Если до первого преобразования возникает ошибка или достигается конец потока файла, возвращается значение EOF для fscanf и fwscanf .
Эти функции проверяют свои параметры. Если stream или format является указателем NULL , вызывается обработчик недопустимых параметров, как описано в статье Проверка параметров. Если продолжение выполнения разрешено, эти функции возвращают EOF и устанавливают для errno значение EINVAL .
Remarks
Функция fscanf считывает данные из текущей позиции stream в расположение, на которое указывает argument (если такое есть). Каждый параметр argument должен быть указателем на переменную, которая имеет тип, соответствующий спецификатору типа в параметре format . format Управляет интерпретацией полей ввода и имеет ту же форму и функцию, что format и аргумент для scanf ; см. Описание format в разделе scanf .
fwscanf — это версия fscanf с расширенными символами; аргумент format для функции fwscanf — строка расширенных символов. Эти функции ведут себя одинаково, если поток открыт в режиме ANSI. fscanf сейчас не поддерживает ввод из потока ЮНИКОДА.
Версии этих функций с суффиксом _l идентичны за исключением того, что они используют переданный параметр языкового стандарта вместо языкового стандарта текущего потока.