scanf()

Считать ввод из стандартного потока ввода (stdin)

Прототип:

#include <stdio.h>
                                       
int scanf( const char *format, 
           ... );

Аргументы:

format: Строка, управляющая форматом входных данных. Определяет дополнительные аргументы, которые необходимо передать функции.
...: Дополнительные аргументы, которые будут заполнены функцией (передаются по адресу). Их состав и перечень определяет format.

Описание:

Функция scanf() считывает ("сканирует") входные данные из stdin под управлением аргумента format, присваивая значения остальным аргументам.

Управляющая строка

Управляющая строка состоит из нуля или более спецификаторов формата, которые определяют тип считываемых данных. Следующие аргументы являются указателями на различные типы данных, которым функция присваивает значения при обработке управляющей строки.

Спецификатор формата может состоять из одного или нескольких символов пробела или:

многобайтовый символ

Любой символ в управляющей строке, кроме символа пробела или символа процента (%), который не является частью спецификатора.

спецификатор преобразования

Последовательность символов в управляющей строке, начинающаяся с символа процента (%), за которой следует:

необязательный знак пропуска преобразования: символ звездочки (*)
необязательное десятичное число, указывающее максимальную ширину поля для преобразования
необязательный спецификатор длины типа; один из h, L или l
символ, определяющий тип преобразования; один из символов: c, d, e, f, g, i, n, o, p, s, u, X, x, [

Поскольку спецификатор формата в управляющей строке обрабатывается, преобразование может завершиться успешно, завершиться с ошибкой из-за отсутствия входных данных или завершиться из-за ошибки сопоставления со спецификатором.

Если во входных данных встречается конец файла до того, как были обработаны какие-либо символы, соответствующие текущему спецификатору (кроме пробелов, где они разрешено), преобразование завершается ошибкой из-за отсутствия данных.

Если наступает конец файла после обработки соответствующего символа, обработка завершается (если не возникает ошибки сопоставления), и функция завершается без обработки следующего спецификатора.

Если преобразование завершается с ошибкой из-за несоответствия входных данных, то данные остаются непрочитанными во входном потоке.

Завершающие символы пробела, включая символы перевода строки, не считываются, если они не совпадают со спецификатором. При сбое преобразования или обнаружении конца управляющей строки считывание завершается и функция завершается.

Когда в управляющей строке встречается один или несколько символов пробела (пробел, горизонтальная табуляция \t, вертикальная табуляция \v, прогон страницы \f, возврат каретки \r, перевод строки \n), считываются входные данные до первого символа, не содержащего пробела, или до тех пор, пока не останется больше никаких данных. Если во входных данных не обнаружено пробелов, то считывание прекращается и функция завершает работу.

Ожидается, что обычный символ в управляющей строке будет соответствовать тому же символу во входном потоке.

Спецификаторы преобразования

Спецификатор преобразования в управляющей строке обрабатывается следующим образом:

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

Спецификатор длины типа

Спецификатор длины типа влияет на преобразование следующим образом:

hh преобразовывает формат d, i, o, u, x, X или `n' для присвоения преобразованного значения объекту типа signed char или unsigned char.
h преобразовывает формата d, i, o, u, x, 'Xилиn(целое число) для присвоения преобразованного значения объекту типаshortилиunsigned short`.
j преобразовывает формат d, i, o, u, x, X или n для присвоения преобразованного значения объекту типа intmax_t или uintmax_t.
l ("эль") преобразовывает формат d, i, o, u, x, X или n (целое число) для присвоения преобразованного значения объекту типа long или unsigned long.
l ("эль") преобразовывает формат a, A, e, E, f, F, g или G для присвоения преобразованного значения объекту типа double.
l ("эль") преобразовывает формат c, s или [ для присвоения преобразованного значения объекту типа wchar_t.
ll (двойная "эль") преобразовывает формат d, i, o, u, x, X или n для присвоения преобразованного значения объекту типа long long или unsigned long long.
L преобразовывает формат a, A, e, E, f, F, g или G для присвоения преобразованного значения объекту типа long double.
t преобразовывает формат d, i, o, u, x, 'Xилиnдля присвоения преобразованного значения объекту типаptrdiff_tили соответствующему типуunsigned`.
z преобразовывает формат d, i, o, u, x, X или `n' для присвоения преобразованного значения объекту типа size_t или соответствующему целочисленному типу со знаком.

Спецификаторы типа преобразования

Допустимыми спецификаторами типа преобразования являются:

a, A, e, E, f, F, g или G: Число с плавающей запятой, бесконечность или NaN, все из которых имеют формат, который ожидается от strtod(). Предполагается, что аргумент указывает на объект типа float.
c: Любая последовательность символов во входном потоке длиной, указанной в ширине поля, или один символ, если ширина поля не указана. Предполагается, что аргумент указывает на первый элемент массива символов достаточного размера, чтобы содержать последовательность, без завершающего символа NUL ('\0'). Для присвоения одного символа достаточно указателя на один объект типа char.

Когда присутствует спецификатор l ("эль"), последовательность символов преобразуется в широкие символы wchar_t, как-будто после вызова mbrtowc(). Преобразованный результат описывается объектом mbstate_t.
d: Десятичное целое число с форматом, который ожидается от strtol(), и основанием 10. Предполагается, что аргумент указывает на объект типа int.
i: Необязательное целое число со знаком с форматом, который ожидается от strtol(), и основанием 0. Предполагается, что аргумент указывает на объект типа int.
n: Входные данные не обрабатываются. Вместо этого символы, которые уже были прочитаны, присваивается объекту типа int, на который указывает аргумент. Количество элементов, которые были считаны и присвоены (возвращаемое значение), не зависит от спецификатора типа преобразования n.
o: Необязательное восьмеричное целое число со знаком с форматом, который ожидается от strtoul(), и основанием 8. Предполагается, что аргумент указывает на объект типа int.
p: Шестнадцатеричное целое число, как описано для преобразования x ниже. Преобразованное значение обозначается как void *, а затем присваивается объекту, на который указывает аргумент. Если последовательность содержит более 8 цифр, преобразование выполняется только для последних 8 цифр в последовательности.
s: Последовательность символов, не содержащих пробелов. Предполагается, что аргумент указывает на первый элемент массива символов достаточного размера, чтобы содержать последовательность символов char, signed char или unsigned char и завершающий символ NUL, который добавляется в результате операции преобразования.

Когда присутствует спецификатор l ("эль"), последовательность символов преобразуется в широкие символы wchar_t, как-будто после вызова mbrtowc(). Преобразованный результат описывается объектом mbstate_t.
u: Десятичное целое беззнаковое число, состоящее из одной или нескольких десятичных цифр. Предполагается, что аргумент указывает на объект типа unsigned int.
x, X: Шестнадцатеричное целое число с форматом, который ожидается от strtoul(), с основанием 16. Предполагается, что аргумент указывает на объект типа unsigned.
[: Функция scanf() поддерживает спецификатор формата общего назначения, называемый набором сканируемых символов scanset. В этом случае определяется набор символов, которые могут быть прочитаны функцией scanf() и присвоены соответствующему массиву символов. Для определения такого набора символы, подлежащие сканированию, необходимо заключить в квадратные скобки. Предполагается, что аргумент указывает на первый элемент массива символов достаточного размера, чтобы содержать последовательность и завершающий символ NUL, который добавляет операция преобразования.

Когда присутствует квалификатор l ("эль"), последовательность символов преобразуется из начального состояния сдвига в широкие символы wchar_t, как если бы был вызов mbrtowc() с mbstate, установленным в 0. Предполагается, что аргумент указывает на первый элемент массива wchar_t достаточного размера, чтобы содержать последовательность и завершающий символ NUL, который добавляет операция преобразования.

Спецификатор типа преобразования включает все символы в наборе сканируемых символов между начальным символом [ и завершающим символом ]. Если спецификация преобразования начинается с [^, то функция считывает все символы, которых нет в наборе сканируемых символов. Если спецификация преобразования начинается с [] или [^], то символ ] включается в набор. (Чтобы считать только ], следует указать %[]].)

A - в наборе сканируемых символов, который не является первым символом, ни вторым, где первый символ является ^, ни последним символом, определяет диапазон совпадающих символов. Этот диапазон состоит из символов, численно превышающих или равных символу перед -, и численно меньших или равных символу после -
%: Символ % (полная спецификация %%).

Спецификатор типа преобразования % обрабатывается как один обычный символ, который соответствует одному символу % во входных данных. Спецификатор типа преобразования, отличный от перечисленных выше, приводит к прекращению считывания и возврату функции с ошибкой.

Возвращаемое значение:

Количество входных аргументов, для которых значения были успешно считаны и сохранены, или EOF, если считывание остановилось, достигнув конца потока ввода до сохранения каких-либо значений.

Примеры:

Cтрока программного кода:

scanf( "%s%*f%3hx%d", name, &hexnum, &decnum );

при входных данных:

some_string 34.555e-3 abc1234

копирует строку "some_string" в массив name, пропускает 34.555e-3, присваивает 0xabc шестнадцатеричному числу hexnum и 1234 десятичному decnum. Возвращаемое значение 3

Программный код:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
                                       
int main( void )
{
    char string1[80], string2[80];
    
    memset( string1, 0, 80 );
    memset( string2, 0, 80 );
                                       
    scanf( "%[abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWZ ]%*2s%[^\n]",
           string1, string2 );
                                       
    printf( "%s\n", string1 );
    printf( "%s\n", string2 );
        
    return (EXIT_SUCCESS);
}

при входных данных:

They may look alike, but they don't perform alike.

присваивает значение "They may look alike" строке string1, пропускает запятую («%*2s» соответствует только запятой; следующий пробел завершает данное поле) и присваивает " but they don't perform alike." строке string2.

Для того, считать дату в формате “Friday March 26 1999”, можно использовать следующий программный код:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
                                       
int main( void )
{
    int  day, year;
    char weekday[10], month[12];
    int  retval;
    
    memset( weekday, 0, 10 );
    memset( month, 0, 12 );
                                       
    retval = scanf( "%s %s %d %d", weekday, month, &day, &year );
    if ( retval != 4 )
    {
        printf( "Error reading date.\n" );
        printf( "Format is: Friday March 26 1999\n" );
        return (EXIT_FAILURE);
    }
        
    printf( "weekday: %s\n", weekday );
    printf( "month: %s\n", month );
    printf( "day: %d\n", day );
    printf( "year: %d\n", year );
        
    return (EXIT_SUCCESS);
}

Классификация:

ANSI, POSIX 1003.1

Безопасность использования
Точка остановки потока: Да
Обработчик прерываний: Нет
Обработчик сигналов: Нет
В потоке: Да

Тематические ссылки:

fscanf(), fwscanf() sscanf(), swscanf(), vfscanf(), vfwscanf(), vscanf(), vsscanf(), vswscanf(), vwscanf(), wscanf()

Предыдущий раздел: Описание API системной библиотеки