.\" -*- coding: UTF-8 -*- .\" Copyright (c) 1990, 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek and the American National Standards Committee X3, .\" on Information Processing Systems. .\" .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" %%%LICENSE_END .\" .\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 .\" .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu .\" modified to resemble the GNU libio setup used in the Linux libc .\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de .\" Modified, aeb, 970121 .\" 2005-07-14, mtk, added description of %n$ form; various text .\" incorporated from the GNU C library documentation ((C) The .\" Free Software Foundation); other parts substantially rewritten. .\" .\" 2008-06-23, mtk .\" Add ERRORS section. .\" Document the 'a' and 'm' modifiers for dynamic string allocation. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH SCANF 3 "13 августа 2020 г." GNU "Руководство программиста Linux" .SH ИМЯ scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- преобразует данные в соответствии с форматом .SH СИНТАКСИС .nf \fB#include \fP .PP \fBint scanf(const char *\fP\fIformat\fP\fB, ...);\fP \fBint fscanf(FILE *\fP\fIstream\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP \fBint sscanf(const char *\fP\fIstr\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP \fB#include \fP .PP \fBint vscanf(const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP \fBint vsscanf(const char *\fP\fIstr\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP \fBint vfscanf(FILE *\fP\fIstream\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP .fi .PP .RS -4 Требования макроса тестирования свойств для glibc (см. \fBfeature_test_macros\fP(7)): .RE .ad l .PP \fBvscanf\fP(), \fBvsscanf\fP(), \fBvfscanf\fP(): .RS 4 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L .ad .RE .SH ОПИСАНИЕ Группа функций \fBscanf\fP() считывает вводимую информацию в соответствии с форматом \fIformat\fP так, как описано ниже. В формате могут указываться \fIопределители преобразования\fP (conversion specifications); результаты каждого преобразования, если они производились, сохраняются по адресам параметров \fIуказателей\fP, передаваемых после \fIformat\fP. Каждый параметр \fIуказатель\fP должен быть того же типа, что и значение, получаемое в результате преобразования данных в соответствии с форматом. .PP Если количество определителей преобразования в \fIformat\fP превышает количество параметров \fIуказателей\fP, то результат не определён. Если количество параметров \fIуказателей\fP превышает количество определителей преобразования, то лишние параметры \fIуказатели\fP вычисляются, но игнорируются. .PP Функция \fBscanf\fP() считывает информацию из стандартного потока ввода \fIstdin\fP; \fBfscanf\fP() считывает информацию из потока, на который указывает \fIstream\fP, а \fBsscanf\fP() считывает информацию из символьной строки, на которую указывает \fIstr\fP. .PP Функция \fBvfscanf\fP() является аналогом \fBvfprintf\fP(3) и читает информацию из потока, на который указывает указатель \fIstream\fP, используя список указателей переменной длины (смотрите \fBstdarg\fP(3)). Функция \fBvscanf\fP() считывает список параметров переменной длины из стандартного ввода, а функция \fBvsscanf\fP() считывает его из строки. Эти функции являются аналогами функций \fBvprintf\fP(3) и \fBvsprintf\fP(3), соответственно. .PP Строка \fIformat\fP состоит из последовательности \fIинструкций\fP (directives), которые описывают порядок обработки входных символов. Если обработка инструкции завершается с ошибкой, то чтение прекращается и \fBscanf\fP() завершает работу. «Отказом» может быть: \fIошибка ввода\fP, то есть недоступность входных символов или \fIошибка совпадения\fP, то есть получены неподходящие данные (смотрите далее). .PP Инструкцией может быть: .TP \(bu Последовательность пробельных символов (пробел, табуляция, символ новой строки и т. д.; смотрите \fBisspace\fP(3)). Эта инструкция совпадает с любым количеством пустого места, включая отсутствие данных. .TP \(bu Обычный символ (т. е., отличный от пробельного или «%»). Такой символ должен точно совпадать со следующим символом входных данных. .TP \(bu Определитель преобразования, который начинается с символа «%» (процент). Последовательность символов ввода преобразуется в соответствии с определителем, а результат помещается в соответствующий параметр \fIуказатель\fP. Если следующий элемент ввода не соответствует определителю преобразования, то преобразование завершается с ошибкой — \fIошибкой совпадения\fP. .PP Каждый \fIопределитель преобразования\fP в \fIformat\fP начинается с символа «%» или последовательности символов «\fB%\fP\fIn\fP\fB$\fP» (смотрите о разнице далее) за которым следует: .TP \(bu Необязательный символ подавления назначения «*»: \fBscanf\fP() читает данные как предписано определителем преобразования, но отбрасывает их. Соответствующий параметр \fIуказатель\fP необязателен, и этот определитель не учитывается в счётчике успешных назначений, возвращаемом \fBscanf\fP(). .TP \(bu Для десятичных преобразований необязательный символ кавычки (\(aq). Указывает, что входное число можно содержать разделитель тысяч, определяемый категорией \fBLC_NUMERIC\fP текущей локали (смотрите \fBsetlocale\fP(3).) Символ кавычки может быть до или после символа подавления \(aq*\(aq. .TP \(bu Необязательный символ «m». Используется в строковых преобразованиях (\fI%s\fP, \fI%c\fP, \fI%[\fP) и освобождает вызывающего от необходимости выделять соответствующий буфер для хранения входных данных: вместо этого \fBscanf\fP() выделяет буфер достаточного размера и присваивает адрес этого буфера соответствующему параметру \fIуказателю\fP, который должен быть указателем на переменную \fIchar\ *\fP (эту переменную не нужно инициализировать перед вызовом). Вызывающий должен вызвать \fBfree\fP(3) для этого буфера, как только он станет ненужным. .TP \(bu Необязательное целое десятичное число, которое задаёт \fIмаксимальную ширину поля\fP. Чтение символов прерывается по достижении этого максимума или при нахождении несовпадающего символа, неважно что случится раньше. В большинстве преобразований начальные пробельные символы отбрасываются (исключения приведены далее), и эти отброшенные символы не учитываются в максимальной ширине поля. В преобразованных строках ввода сохраняется конечный байт null (\(aq\e0\(aq) для отметки конца ввода; в максимальной ширине поля он также не учитывается. .TP \(bu An optional \fItype modifier character\fP. For example, the \fBl\fP type modifier is used with integer conversions such as \fB%d\fP to specify that the corresponding \fIpointer\fP argument refers to a \fIlong\fP rather than a pointer to an \fIint\fP. .TP \(bu \fIОпределитель преобразования\fP, который задаёт тип входного преобразования. .PP Определители преобразования в \fIformat\fP бывают двух видов: начинающиеся с «%» и начинающиеся с «\fB%\fP\fIn\fP\fB$\fP». Эти два вида не должны использоваться одновременно в строке \fIformat\fP, за исключением случая, когда строка, содержащая определители «\fB%\fP\fIn\fP\fB$\fP», может включать \fB%%\fP и \fB%*\fP. Если в \fIformat\fP содержатся определители «%», то они задаются в порядке появления параметров \fIуказателей\fP, указанных после. В форме «\fB%\fP\fIn\fP\fB$\fP» (есть в POSIX.1\-2001, но отсутствует в C99), \fIn\fP — это десятичное целое, которое задаёт в какое место должен быть помещён ввод, то есть указывает на расположение \fIn\fP\-го параметра \fIуказателя\fP, передаваемого после \fIformat\fP. .SS Преобразования Следующие \fIсимволы модификаторов типа\fP (type modifier characters) могут появляться в определении преобразования: .TP \fBh\fP Indicates that the conversion will be one of \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP and the next pointer is a pointer to a \fIshort\fP or \fIunsigned short\fP (rather than \fIint\fP). .TP \fBhh\fP Как \fBh\fP, но следующий указатель — указатель на \fIsigned char\fP или \fIunsigned char\fP. .TP \fBj\fP Как \fBh\fP, но следующий указатель — указатель на \fIintmax_t\fP или \fIuintmax_t\fP. Этот модификатор появился в C99. .TP \fBl\fP .\" This use of l was introduced in Amendment 1 to ISO C90. Indicates either that the conversion will be one of \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP and the next pointer is a pointer to a \fIlong\fP or \fIunsigned long\fP (rather than \fIint\fP), or that the conversion will be one of \fBe\fP, \fBf\fP, or \fBg\fP and the next pointer is a pointer to \fIdouble\fP (rather than \fIfloat\fP). Specifying two \fBl\fP characters is equivalent to \fBL\fP. If used with \fB%c\fP or \fB%s\fP, the corresponding parameter is considered as a pointer to a wide character or wide\-character string respectively. .TP \fBL\fP .\" MTK, Jul 05: The following is no longer true for modern .\" ANSI C (i.e., C99): .\" (Note that long long is not an .\" ANSI C .\" type. Any program using this will not be portable to all .\" architectures). Обозначает, что преобразование будет одним из \fBe\fP, \fBf\fP или \fBg\fP и следующий указатель является указателем на \fIlong double\fP или преобразование будет одним из \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP или \fBx\fP и следующий указатель является указателем на \fIlong long\fP. .TP \fBq\fP Эквивалентен \fBL\fP. Данный определитель отсутствует в ANSI C. .TP \fBt\fP Как \fBh\fP, но следующий указатель — указатель на \fIptrdiff_t\fP. Этот модификатор появился в C99. .TP \fBz\fP Как \fBh\fP, но следующий указатель — указатель на \fIsize_t\fP. Этот модификатор появился в C99. .PP Доступны следующие \fIопределители преобразования\fP: .TP \fB%\fP Совпадает с литерой «%». То есть \fB%\&%\fP в строке формата соответствует одиночному символу данных «%». Преобразование не выполняется (но начальные пробельные символы отбрасываются) и назначения не происходит. .TP \fBd\fP .\" .TP .\" .B D .\" Equivalent to .\" .IR ld ; .\" this exists only for backward compatibility. .\" (Note: thus only in libc4 .\" In libc5 and glibc the .\" .B %D .\" is silently ignored, causing old programs to fail mysteriously.) Совпадает с необязательным знаковым десятичным целым; следующий указатель должен быть указателем на \fIint\fP. .TP \fBi\fP Совпадает с необязательным знаковым целым; следующий указатель должен быть указателем на \fIint\fP. Целое считывается как шестнадцатеричное число, если начинается с \fI0x\fP или \fI0X\fP, как восьмеричное, если начинается с \fI0\fP и как десятичное в остальных случаях. Используются только символы, подходящие для работы с выбранным основанием системы счисления. .TP \fBo\fP Совпадает с необязательным беззнаковым восьмеричным целым; следующий указатель должен быть указателем на \fIunsigned int\fP. .TP \fBu\fP Совпадает с необязательным беззнаковым десятичным целым; следующий указатель должен быть указателем на \fIunsigned int\fP. .TP \fBx\fP Matches an unsigned hexadecimal integer (that may optionally begin with a prefix of \fI0x\fP or \fI0X\fP, which is discarded); the next pointer must be a pointer to \fIunsigned int\fP. .TP \fBX\fP Эквивалентно \fBx\fP. .TP \fBf\fP Совпадает с необязательным знаковым числом с плавающей запятой; следующий указатель должен быть указателем на \fIfloat\fP. .TP \fBe\fP Эквивалентно \fBf\fP. .TP \fBg\fP Эквивалентно \fBf\fP. .TP \fBE\fP Эквивалентно \fBf\fP. .TP \fBa\fP (C99) Эквивалентно \fBf\fP. .TP \fBs\fP Совпадает с последовательностью непробельных символов; следующий указатель должен указывать на первый элемент массива символов достаточной длины для сохранения входной последовательности и завершающего байта null (\(aq\e0\(aq), который добавляется автоматически. Входная строка обрывается при появлении пробельного символа или достижении максимальной ширины поля, неважно что случится раньше. .TP \fBc\fP Совпадает с последовательностью символов, чья длина задаётся \fIмаксимальной шириной поля\fP (по умолчанию 1); следующий указатель должен быть указателем на \fIchar\fP, и должно быть достаточно места для всех символов (завершающий байт null не добавляется). Обычный пропуск начальных пробелов не выполняется. Чтобы пропустить пробелы, явно укажите их в формате. .TP \fB\&[\fP Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to \fIchar\fP, and there must be enough room for all the characters in the string, plus a terminating null byte. The usual skip of leading white space is suppressed. The string is to be made up of characters in (or not in) a particular set; the set is defined by the characters between the open bracket \fB[\fP character and a close bracket \fB]\fP character. The set \fIexcludes\fP those characters if the first character after the open bracket is a circumflex (\fB\(ha\fP). To include a close bracket in the set, make it the first character after the open bracket or the circumflex; any other position will end the set. The hyphen character \fB\-\fP is also special; when placed between two other characters, it adds all intervening characters to the set. To include a hyphen, make it the last character before the final close bracket. For instance, \fB[\(ha]0\-9\-]\fP means the set "everything except close bracket, zero through nine, and hyphen". The string ends with the appearance of a character not in the (or, with a circumflex, in) set or when the field width runs out. .TP \fBp\fP Matches a pointer value (as printed by \fB%p\fP in \fBprintf\fP(3)); the next pointer must be a pointer to a pointer to \fIvoid\fP. .TP \fBn\fP Ничего не ожидается; вместо этого количество символов, использованных к настоящему времени из ввода, сохраняется по следующему указателю, который должен быть указателем на \fIint\fP. Это \fIне\fP преобразование и \fIне\fP увеличивает счётчик, возвращаемый функцией. Назначение может подавляться при указании символа подавления назначения \fB*\fP, но влияние этого на возвращаемое значение не определено. Поэтому преобразования \fB%*n\fP лучше не использовать. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" При успешном выполнении данные функции возвращают количество входных совпавших и назначенных элементов, которое может быть меньше, чем предусматривалось, или даже равно нулю, в случае преждевременной ошибки при поиске совпадений. .PP Если конец входных данных был достигнут раньше, чем произошло хотя бы одно совпадение или при ошибке совпадения возвращается значение \fBEOF\fP. Значение \fBEOF\fP также возвращается при ошибке чтения; в этом случае для потока устанавливается индикатор ошибки (смотрите \fBferror\fP(3)), а в \fIerrno\fP указывается номер ошибки. .SH ОШИБКИ .TP \fBEAGAIN\fP Файловый дескриптор \fIstream\fP помечен как неблокирующий, а чтение вызвало бы блокировку. .TP \fBEBADF\fP Неправильный файловый дескриптор для \fIstream\fP или он не открыт на чтение. .TP \fBEILSEQ\fP Из входной байтовой последовательности невозможно создать корректный символ. .TP \fBEINTR\fP Операция чтения была прервана сигналом; смотрите \fBsignal\fP(7). .TP \fBEINVAL\fP Недостаточно параметров или \fIformat\fP равен NULL. .TP \fBENOMEM\fP Не хватает памяти. .TP \fBERANGE\fP Результат преобразования целого превысил бы размер, который можно хранить в соответствующем целочисленном типе. .SH АТРИБУТЫ Описание терминов данного раздела смотрите в \fBattributes\fP(7). .TS allbox; lbw20 lb lb l l l. Интерфейс Атрибут Значение T{ \fBscanf\fP(), \fBfscanf\fP(), .br \fBsscanf\fP(), \fBvscanf\fP(), .br \fBvsscanf\fP(), \fBvfscanf\fP() T} Безвредность в нитях MT\-Safe locale .TE .sp 1 .SH "СООТВЕТСТВИЕ СТАНДАРТАМ" Функции \fBfscanf\fP(), \fBscanf\fP() и \fBsscanf\fP() соответствуют C89, C99 и POSIX.1\-2001. В этих стандартах не определена ошибка \fBERANGE\fP. .PP Определитель \fBq\fP в 4.4BSD используется для \fIlong long\fP, а определители \fBll\fP или \fBL\fP используются в GNU для преобразования целых чисел. .PP Версия Linux этих функций основана на библиотеке \fIGNU\fP \fIlibio\fP. Более точное описание функций можно найти в документации в формате \fIinfo\fP на \fIGNU\fP \fIlibc (glibc\-1.08)\fP. .SH ЗАМЕЧАНИЯ .SS "Модификатор выделения\-назначения «a»" Первоначально, в библиотеке GNU C поддерживалось динамическое выделение памяти для входных строк при указании символа \fBa\fP (нестандартное расширение) (это свойство существует до glibc 2.0). То есть можно указать \fBscanf\fP() выделить буфер под входную строку, передав в указателе только указатель на буфер \fI*buf\fP: .PP char *buf; scanf("%as", &buf); .PP Использование буквы \fBa\fP для этой цели проблематично, так как \fBa\fP также используется в стандарте ISO C как синоним \fBf\fP (ввод данных с плавающей запятой). В POSIX.1\-2008 для назначения с выделением определён модификатор \fBm\fP (смотрите в ОПИСАНИЕ выше). .PP Заметим, что модификатор \fBa\fP недоступен, если программа скомпилирована посредством \fIgcc \-std=c99\fP или \fIgcc \-D_ISOC99_SOURCE\fP (если не определён \fB_GNU_SOURCE\fP); в этом случае \fBa\fP рассматривается как определитель чисел с плавающей запятой (смотрите выше). .PP Поддержка модификатора \fBm\fP была добавлена в glibc начиная с версии 2.7, и в новых программах нужно использовать этот модификатор вместо \fBa\fP. .PP Стандартизированный в POSIX модификатор \fBm\fP имеет дополнительные преимущества над \fBa\fP: .IP * 2 Он может также применяться к определителям преобразования \fB%c\fP (например, \fB%3mc\fP). .IP * Исчезает неоднозначность с определителем преобразования чисел с плавающей запятой \fB%a\fP (не подвержен влиянию \fIgcc \-std=c99\fP). .SH ДЕФЕКТЫ Все функции полностью соответствуют C89, но предоставляют дополнительные определители \fBq\fP и \fBa\fP, а также дополнительные возможности определителей \fBL\fP и \fBl\fP. Последнее может считаться дефектом, так как это изменяет поведение определителей, заданное в C89. .PP Некоторые комбинации модификаторов типов и определителей преобразования, определённые в ANSI C, не имеют смысла (например, \fB%Ld\fP). Хотя они могут иметь хорошо описанное поведение в Linux, это не обязательно так на других архитектурах. Поэтому, обычно, лучше использовать модификаторы, не определённые в ANSI C, то есть использовать \fBq\fP вместо \fBL\fP в комбинации с преобразованием \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP и \fBX\fP или \fBll\fP. .PP Работа \fBq\fP отличается от работы в 4.4BSD, так как может использоваться при преобразовании вещественных числе подобно \fBL\fP. .SH ПРИМЕРЫ Чтобы использовать определитель динамического выделения при преобразовании, укажите \fBm\fP в качестве модификатора длины (в виде \fB%ms\fP или \fB%m[\fP\fIдиапазон\fP\fB]\fP). Вызывающий должен вызвать \fBfree\fP(3) для возвращённой строки как в следующем примере: .PP .in +4n .EX char *p; int n; errno = 0; n = scanf("%m[a\-z]", &p); if (n == 1) { printf("чтение: %s\en", p); free(p); } else if (errno != 0) { perror("scanf"); } else { fprintf(stderr, "Нет совпадающих символов\en"); } .EE .in .PP Как показано в примере выше, необходимо вызывать \fBfree\fP(3) только, если при вызове \fBscanf\fP() была прочитана строка. .SH "СМ. ТАКЖЕ" \fBgetc\fP(3), \fBprintf\fP(3), \fBsetlocale\fP(3), \fBstrtod\fP(3), \fBstrtol\fP(3), \fBstrtoul\fP(3) .SH ЗАМЕЧАНИЯ Эта страница является частью проекта Linux \fIman\-pages\fP версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу \%https://www.kernel.org/doc/man\-pages/. .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Alexander Golubev , Azamat Hackimov , Hotellook, Nikita , Spiros Georgaras , Vladislav , Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .