vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s

int vscanf( const char *restrict format, va_list vlist );

int vfscanf( FILE *restrict stream, const char *restrict format, 
             va_list vlist );

int vsscanf( const char *restrict buffer, const char *restrict format, 
             va_list vlist );

int vscanf_s(const char *restrict format, va_list vlist);

int vfscanf_s( FILE *restrict stream, const char *restrict format,
               va_list vlist);

int vsscanf_s( const char *restrict buffer, const char *restrict format,
               va_list vlist);

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

Параметры

Строка формата состоит из

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

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

Для каждого спецификатора преобразования, отличного от 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 1765.

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

Примечания

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

Пример

#include <stdio.h>
#include <stdbool.h>
#include <stdarg.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

Ссылки

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

См. также