scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Считывает отформатированные данные из стандартного входного потока. Эти версии , _wscanf_l_scanf_lwscanf имеют улучшения безопасности, как описано в функциях scanfбезопасности в CRT.

Синтаксис

int scanf_s(
   const char *format [,
   argument]...
);
int _scanf_s_l(
   const char *format,
   _locale_t locale [,
   argument]...
);
int wscanf_s(
   const wchar_t *format [,
   argument]...
);
int _wscanf_s_l(
   const wchar_t *format,
   _locale_t locale [,
   argument]...
);

Параметры

format
Строка управления форматированием.

argument
Необязательные аргументы.

locale
Используемый языковой стандарт.

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

Возвращает количество полей, успешно преобразованных и назначенных. Возвращаемое значение не включает поля, которые были прочитаны, но не назначены. Возвращаемое значение 0 указывает, что поля не назначены. Возвращаемое значение является EOF ошибкой или если символ конца файла или символ конца строки найден в первой попытке считывания символа. Если format это NULL указатель, вызывается обработчик недопустимых параметров, как описано в разделе "Проверка параметров". Если выполнение может быть продолжено, то функции scanf_s и wscanf_s возвращают ошибку EOF и устанавливают для errno значение EINVAL.

Сведения об этих и других кодах ошибок см. в разделе errno, _doserrno_sys_errlistи _sys_nerr.

Замечания

Функция scanf_s считывает данные из стандартного входного потока stdinи записывает его в argument. Каждый из них argument должен быть указателем на тип переменной, соответствующий описательу типов.format Если копирование производится между перекрывающимися строками, поведение не определено.

wscanf_s — это версия scanf_sс расширенными символами; аргумент format для wscanf_s — строка расширенных символов. wscanf_s и scanf_s ведут себя одинаково, если поток открыт в режиме ANSI. scanf_s сейчас не поддерживает ввод из потока ЮНИКОДА.

Версии этих функций с суффиксом идентичны, за исключением того, что _l они используют locale параметр вместо текущего языкового стандарта потока.

В отличие scanf от и wscanf, scanf_s и wscanf_s требуется указать размер буфера для некоторых параметров. Укажите размеры для всех параметров набора элементов управления, а sSтакже для всех c, или Cстроковых элементов [] управления. Размер буфера в символах передается в качестве другого параметра. Он сразу же следует указателю на буфер или переменную. Например, если вы читаете строку, размер буфера для этой строки передается следующим образом:

char s[10];
scanf_s("%9s", s, (unsigned)_countof(s)); // buffer size is 10, width specification is 9

Размер буфера содержит значение NULL терминала. Можно использовать поле спецификации ширины, чтобы убедиться, что маркер, который считывается в буфере. Если маркер слишком велик, ничего не записывается в буфер, если не существует спецификации ширины.

Примечание.

Параметр размера имеет тип unsigned, а не size_t. Для преобразования значения size_t в значение unsigned для 64-разрядной конфигурации сборки следует использовать static_cast.

Параметр размера буфера описывает максимальное количество символов, а не байтов. В этом примере ширина типа буфера не соответствует ширине описателя формата.

wchar_t ws[10];
wscanf_s(L"%9S", ws, (unsigned)_countof(ws));

Описатель S формата означает использование ширины символов, которая является противоположной ширине по умолчанию, поддерживаемой функцией. Ширина символа — однобайт, но функция поддерживает двойные байты. Этот пример считывает строку до девяти однобайтовых символов и помещает их в буфер двухбайтовых символов. Символы обрабатываются как однобайтовые значения; первые два символа сохраняются в ws[0], вторые два сохраняются в ws[1] и т. д.

В этом примере считывается один символ:

char c;
scanf_s("%c", &c, 1);

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

char c[4];
scanf_s("%4c", c, (unsigned)_countof(c)); // not null terminated

Дополнительные сведения см. в разделе scanf "Спецификация ширины".

Сопоставления подпрограмм универсального текста

TCHAR.H Обычной	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

Дополнительные сведения см. в полях спецификации форматирования: scanf и wscanf функций.

Требования

Маршрут	Обязательный заголовок
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> или <wchar.h>

Консоль не поддерживается в приложениях универсальная платформа Windows (UWP). Стандартные дескрипторы потоков и stderr должны быть перенаправлены перед тем, как функции времени выполнения C могут использовать их в приложениях stdinstdoutUWP. Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

// crt_scanf_s.c
// This program uses the scanf_s and wscanf_s functions
// to read formatted input.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   int      i,
            result;
   float    fp;
   char     c,
            s[80];
   wchar_t  wc,
            ws[80];

   result = scanf_s( "%d %f %c %C %s %S", &i, &fp, &c, 1,
                     &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   printf( "The number of fields input is %d\n", result );
   printf( "The contents are: %d %f %c %C %s %S\n", i, fp, c,
           wc, s, ws);
   result = wscanf_s( L"%d %f %hc %lc %S %ls", &i, &fp, &c, 2,
                      &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   wprintf( L"The number of fields input is %d\n", result );
   wprintf( L"The contents are: %d %f %C %c %hs %s\n", i, fp,
            c, wc, s, ws);
}

Эта программа создает следующие выходные данные для этих входных данных:

71 98.6 h z Byte characters
36 92.3 y n Wide characters

The number of fields input is 6
The contents are: 71 98.599998 h z Byte characters
The number of fields input is 6
The contents are: 36 92.300003 y n Wide characters

См. также

Поддержка математических и плавающих точек
Потоковый ввод-вывод
Локаль
fscanf, _fscanf_l, fwscanf, _fwscanf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
sscanf, _sscanf_l, swscanf, _swscanf_l