Namespaces
Variants

    вscanf, вfscanf, вsscanf, вscanf_s, вfscanf_s, вsscanf_s

    С ru.cppreference.net
    < c | io
     
    C
     
    Файловый ввод/вывод
    Типы и объекты
            
    Функции
    Доступ к файлам
    (C11)
    (C11)  
    (C95)
    Неформатированный ввод/вывод
    (C95)(C95)
    (C95)
    (C95)(C95)
    (C95)
    (C95)
    (C95)
    (C95)

    Форматированный ввод
    (C99)(C99)(C99)(C11)(C11)(C11)
    (C99)(C99)(C99)(C11)(C11)(C11)  
    Прямой ввод/вывод
    Форматированный вывод
    Позиционирование в файле
    Обработка ошибок
    Операции с файлами
     
    Определено в заголовке <stdio.h> 
    int vscanf( const char* restrict format, va_list vlist );
    		(1) (начиная с C99) 
    int vfscanf( FILE* restrict stream, const char* restrict format,
             va_list vlist );
    		(2) (начиная с C99) 
    int vsscanf( const char* restrict buffer, const char* restrict format,
             va_list vlist );
    		(3) (начиная с C99) 
    int vscanf_s(const char* restrict format, va_list vlist);
    		(4) (начиная с C11) 
    int vfscanf_s( FILE* restrict stream, const char* restrict format,
               va_list vlist);
    		(5) (начиная с C11) 
    int vsscanf_s( const char* restrict buffer, const char* restrict format,
               va_list vlist);
    		(6) (начиная с C11)

    Считывает данные из различных источников, интерпретирует их в соответствии с format и сохраняет результаты в места, определённые через vlist.

    1) Считывает данные из stdin
    2) Считывает данные из файлового потока stream
    3) Считывает данные из строки символов, завершающейся нулевым символом, buffer. Достижение конца строки эквивалентно достижению конца файла для fscanf
    4-6) То же, что и (1-3), за исключением того, что спецификаторы преобразования %c, %s и %[ ожидают по два аргумента (обычный указатель и значение типа rsize_t, указывающее размер принимающего массива, которое может быть 1 при чтении с %c в один символ) и за исключением того, что следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений:
    • любой аргумент типа указателя является нулевым указателем
    • format, stream или buffer является нулевым указателем
    • количество символов, которое было бы записано через %c, %s или %[, включая завершающий нулевой символ, превысило бы второй аргумент (rsize_t), предоставленный для каждого из этих спецификаторов преобразования
    • опционально, любая другая обнаруживаемая ошибка, например неизвестный спецификатор преобразования
    Как и все функции с проверкой границ, vscanf_s, vfscanf_s и vsscanf_s гарантированно доступны только в том случае, если __STDC_LIB_EXT1__ определена реализацией и если пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 до включения <stdio.h>.

    Параметры

    stream - входной файловый поток для чтения
    buffer - указатель на строку символов, завершающуюся нулевым символом, для чтения
    format - указатель на строку символов, завершающуюся нулевым символом, определяющую, как читать входные данные
    vlist - список аргументов переменной длины, содержащий принимающие аргументы.


    Строка format состоит из

    • непробельных многобайтовых символов, отличных от %: каждый такой символ в строке формата потребляет ровно один идентичный символ из входного потока или приводит к сбою функции, если следующий символ в потоке не равен ему.
    • пробельных символов: любой одиночный пробельный символ в строке формата потребляет все доступные последовательные пробельные символы из входного потока (определяется как при вызове isspace в цикле). Обратите внимание, что нет различия между "\n", " ", "\t\t" или другими пробельными символами в строке формата.
    • спецификаций преобразования. Каждая спецификация преобразования имеет следующий формат:
    • вводный символ %.
    • (необязательно) символ подавления присваивания *. Если этот параметр присутствует, функция не присваивает результат преобразования никакому принимающему аргументу.
    • (необязательно) целочисленное число (больше нуля), которое задаёт максимальную ширину поля, то есть максимальное количество символов, которое функция может потребить при выполнении преобразования, заданного текущей спецификацией преобразования. Обратите внимание, что %s и %[ могут привести к переполнению буфера, если ширина не указана.
    • (необязательно) модификатор длины, который задаёт размер принимающего аргумента, то есть фактический целевой тип. Это влияет на точность преобразования и правила переполнения. Целевой тип по умолчанию различается для каждого типа преобразования (см. таблицу ниже).
    • спецификатор формата преобразования.

    Доступны следующие спецификаторы формата:

    Спецификатор
    преобразования     		Пояснение Ожидаемый
    тип аргумента
    Модификатор длины→ hh h нет l ll j z t L
    Доступен только с C99→ Да Да Да Да Да
    %
    Сопоставляет литерал %.
    		 N/A N/A N/A N/A N/A N/A N/A N/A N/A
    c

    Сопоставляет символ или последовательность символов.

    • Если используется спецификатор ширины, сопоставляет ровно width символов (аргумент должен быть указателем на массив с достаточным местом).
    • В отличие от %s и %[, не добавляет нулевой символ в конец массива.
    		 N/A N/A
    char*
    wchar_t*
    		 N/A N/A N/A N/A N/A
    s

    Сопоставляет последовательность непробельных символов (строку).

    • Если используется спецификатор ширины, сопоставляет до width или до первого пробельного символа, в зависимости от того, что наступит раньше.
    • Всегда сохраняет нулевой символ в дополнение к сопоставленным символам (поэтому массив аргумента должен иметь место как минимум для width+1 символов).
    [set ]

    Сопоставляет непустую последовательность символов из set символов.

    • Если первый символ набора — ^, то сопоставляются все символы, не входящие в набор.
    • Если набор начинается с ] или ^], то символ ] также включается в набор.
    • Определяется реализацией, может ли символ - в не начальной позиции в наборе сканирования указывать на диапазон, как в [0-9].
    • Если используется спецификатор ширины, сопоставляет только до width.
    • Всегда сохраняет нулевой символ в дополнение к сопоставленным символам (поэтому массив аргумента должен иметь место как минимум для width+1 символов).
    d

    Сопоставляет десятичное целое число.

    • Формат числа такой же, как ожидается strtol со значением 10 для аргумента base.
    signed char* или unsigned char*
    signed short* или unsigned short*
    signed int* или unsigned int*
    signed long* или unsigned long*
    signed long long* или unsigned long long*
    intmax_t* или uintmax_t*
    size_t*
    ptrdiff_t*
    		 N/A
    b (C23)

    Сопоставляет беззнаковое двоичное целое число.

    • Формат числа такой же, как ожидается strtoul со значением 2 для аргумента base.
    i

    Сопоставляет целое число.

    • Формат числа такой же, как ожидается strtol со значением 0 для аргумента base (основание определяется по первым распознанным символам).
    u

    Сопоставляет беззнаковое десятичное целое число.

    • Формат числа такой же, как ожидается strtoul со значением 10 для аргумента base.
    o

    Сопоставляет беззнаковое восьмеричное целое число.

    • Формат числа такой же, как ожидается strtoul со значением 8 для аргумента base.
    x
    X

    Сопоставляет беззнаковое шестнадцатеричное целое число.

    • Формат числа такой же, как ожидается strtoul со значением 16 для аргумента base.
    n

    Возвращает количество символов, прочитанных на данный момент.

    • Входные данные не потребляются. Не увеличивает счётчик присваиваний.
    • Если для спецификатора определён оператор подавления присваивания, поведение не определено.
    a (C99)
    A (C99)
    e
    E
    f
    F (C99)
    g
    G

    Сопоставляет число с плавающей запятой.

    • Формат числа такой же, как ожидается strtof.
    		 N/A N/A
    float*
    double*
    		 N/A N/A N/A N/A
    long double*
    p

    Сопоставляет определённую реализацией последовательность символов, представляющую указатель.

    • printfСемейство функций должно порождать ту же последовательность с помощью спецификатора формата %p.
    		 N/A N/A
    void**
    		 N/A N/A N/A N/A N/A N/A
    Примечания

    Для каждого спецификатора преобразования, кроме n, самая длинная последовательность входных символов, которая не превышает заданную максимальную ширину поля и которая либо точно соответствует тому, что ожидает спецификатор преобразования, либо является префиксом последовательности, которую он ожидал бы, потребляется из потока. Первый символ, если он есть, после этой потреблённой последовательности остаётся непрочитанным. Если потреблённая последовательность имеет нулевую длину или если потреблённая последовательность не может быть преобразована, как указано выше, происходит ошибка сопоставления, если только конец файла, ошибка кодирования или ошибка чтения не предотвратили ввод из потока, в этом случае это ошибка ввода.

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

    Все спецификаторы преобразования, кроме [, c и n, потребляют и отбрасывают все ведущие пробельные символы (определяется как при вызове isspace) перед попыткой разбора входных данных. Эти потреблённые символы не учитываются в заданной максимальной ширине поля.

    Спецификаторы преобразования lc, ls и l[ выполняют преобразование многобайтовых символов в широкие символы, как при вызове mbrtowc с объектом mbstate_t, инициализированным нулём перед преобразованием первого символа.

    Спецификаторы преобразования s и [ всегда сохраняют завершающий нулевой символ в дополнение к сопоставленным символам. Размер целевого массива должен быть как минимум на единицу больше заданной ширины поля. Использование %s или %[ без указания размера целевого массива так же опасно, как gets.

    Правильные спецификации преобразования для целочисленных типов фиксированной ширины (int8_t и т. д.) определены в заголовке <inttypes.h> (хотя SCNdMAX, SCNuMAX и т. д. являются синонимами %jd, %ju и т. д.).

    Существует точка последовательности после действия каждого спецификатора преобразования; это позволяет сохранять несколько полей в одну и ту же «принимающую» переменную.

    При разборе неполного числа с плавающей запятой, которое заканчивается показателем степени без цифр, например при разборе "100er" со спецификатором преобразования %f, последовательность "100e" (самый длинный префикс возможно допустимого числа с плавающей запятой) потребляется, что приводит к ошибке сопоставления (потреблённая последовательность не может быть преобразована в число с плавающей запятой), при этом "r" остаётся. Некоторые существующие реализации не следуют этому правилу и откатываются, чтобы потреблять только "100", оставляя "er", например, glibc bug 1765.

    Если спецификация преобразования недопустима, поведение не определено.

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

    1-3) Количество успешно присвоенных принимающих аргументов или EOF, если ошибка чтения произошла до присвоения первого принимающего аргумента.
    4-6) То же, что и (1-3), за исключением того, что EOF также возвращается при нарушении ограничения времени выполнения.

    Примечания

    Все эти функции вызывают va_arg по крайней мере один раз, значение arg не определено после возврата. Эти функции не вызывают va_end, и это должен сделать вызывающий код.

    Пример

    Запустить этот код
    #include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>

bool checked_sscanf(int count, const char* buf, const char* fmt, ...)
{
    va_list ap;
    va_start(ap, fmt);
    int rc = vsscanf(buf, fmt, ap);
    va_end(ap);
    return rc == count;
}

int main(void)
{
    int n, m;

    printf("Parsing '1 2'...");
    if (checked_sscanf(2, "1 2", "%d %d", &n, &m))
        puts("success");
    else
        puts("failure");

    printf("Parsing '1 a'...");
    if (checked_sscanf(2, "1 a", "%d %d", &n, &m))
        puts("success");
    else
        puts("failure");
}

    Вывод: 

    Parsing '1 2'...success
Parsing '1 a'...failure

    Ссылки

    • Стандарт C23 (ISO/IEC 9899:2024):
    • 7.21.6.9 Функция vfscanf (p: TBD)
    • 7.21.6.11 Функция vscanf (p: TBD)
    • 7.21.6.14 Функция vsscanf (p: TBD)
    • K.3.5.3.9 Функция vfscanf_s (p: TBD)
    • K.3.5.3.11 Функция vscanf_s (p: TBD)
    • K.3.5.3.14 Функция vsscanf_s (p: TBD)
    • Стандарт C17 (ISO/IEC 9899:2018):
    • 7.21.6.9 Функция vfscanf (p: TBD)
    • 7.21.6.11 Функция vscanf (p: TBD)
    • 7.21.6.14 Функция vsscanf (p: TBD)
    • K.3.5.3.9 Функция vfscanf_s (p: TBD)
    • K.3.5.3.11 Функция vscanf_s (p: TBD)
    • K.3.5.3.14 Функция vsscanf_s (p: TBD)
    • Стандарт C11 (ISO/IEC 9899:2011):
    • 7.21.6.9 Функция vfscanf (p: 327)
    • 7.21.6.11 Функция vscanf (p: 328)
    • 7.21.6.14 Функция vsscanf (p: 330)
    • K.3.5.3.9 Функция vfscanf_s (p: 597-598)
    • K.3.5.3.11 Функция vscanf_s (p: 599)
    • K.3.5.3.14 Функция vsscanf_s (p: 602)
    • Стандарт C99 (ISO/IEC 9899:1999):
    • 7.19.6.9 Функция vfscanf (p: 293)
    • 7.19.6.11 Функция vscanf (p: 294)
    • 7.19.6.14 Функция vsscanf (p: 295)

    См. также

    (C11)(C11)(C11)
    		 читает форматированный ввод из stdin, файлового потока или буфера
    (функция)
    (C99)(C11)(C11)(C11)(C11)
    		 печатает форматированный вывод в stdout, файловый поток или буфер
    с использованием списка аргументов переменной длины
    (функция)
    Документация C++ для vscanf, vfscanf, vsscanf