_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64

Предоставляет сведения о первом экземпляре имени файла, соответствующему файлу, указанному в аргументе filespec.

Синтаксис

intptr_t _findfirst(
   const char *filespec,
   struct _finddata_t *fileinfo
);
intptr_t _findfirst32(
   const char *filespec,
   struct _finddata32_t *fileinfo
);
intptr_t _findfirst64(
   const char *filespec,
   struct _finddata64_t *fileinfo
);
intptr_t _findfirsti64(
   const char *filespec,
   struct _finddatai64_t *fileinfo
);
intptr_t _findfirst32i64(
   const char *filespec,
   struct _finddata32i64_t *fileinfo
);
intptr_t _findfirst64i32(
   const char *filespec,
   struct _finddata64i32_t *fileinfo
);
intptr_t _wfindfirst(
   const wchar_t *filespec,
   struct _wfinddata_t *fileinfo
);
intptr_t _wfindfirst32(
   const wchar_t *filespec,
   struct _wfinddata32_t *fileinfo
);
intptr_t _wfindfirst64(
   const wchar_t *filespec,
   struct _wfinddata64_t *fileinfo
);
intptr_t _wfindfirsti64(
   const wchar_t *filespec,
   struct _wfinddatai64_t *fileinfo
);
intptr_t _wfindfirst32i64(
   const wchar_t *filespec,
   struct _wfinddata32i64_t *fileinfo
);
intptr_t _wfindfirst64i32(
   const wchar_t *filespec,
   struct _wfinddata64i32_t *fileinfo
);

Параметры

filespec
Спецификация целевого файла (может содержать подстановочные знаки).

fileinfo
Буфер сведений о файле.

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

В случае успешного выполнения возвращает уникальный дескриптор поиска, _findfirst определяющий файл или группу файлов, которые соответствуют filespec спецификации, которые можно использовать в последующем вызове _findnext или в _findclose. _findfirst В противном случае возвращает значение -1 и задает errno одно из следующих значений.

Значение errno	Condition
EINVAL	Недопустимый параметр: filespec или fileinfo имеет значение NULL. Или операционная система возвратила непредвиденную ошибку.
ENOENT	Спецификация файла, которую не удалось сопоставить.
ENOMEM	Недостаток памяти.
EINVAL	Недопустимая спецификация имени файла или длина заданного имени файла больше MAX_PATH.

Дополнительные сведения об этих и других кодах возврата см. в разделе errno, _doserrnoи _sys_nerr_sys_errlist.

Если недопустимый параметр передается, эти функции вызывают обработчик недопустимых параметров, как описано в разделе "Проверка параметров".

Замечания

После завершения вызова необходимо выполнить вызов _findclose с _findfirst помощью функции или _findnext функции (или любых вариантов), предоставленного для успешного выполнения вызова _findfirst . _findclose освобождает ресурсы, используемые этими функциями в приложении. Вызов _findclose недопустимого дескриптора возвращает -1 и задает errno значение EINVAL.

Варианты этих функций с w префиксом являются версиями расширенных символов; в противном случае они идентичны соответствующим однобайтовым функциям.

Варианты этих функций поддерживают 32- или 64-разрядные типы времени и 32- или 64-разрядные размеры файлов. Первый числовой суффикс (32 или 64) указывает размер типа времени; второй суффикс i32 или i64 показывает, представлен ли размер файла как 32- или 64-разрядное целое число. Сведения о том, какие версии поддерживают 32- и 64-разрядные типы времени и размеры файлов, см. в следующей таблице. Или i32i64 суффикс опущен, если он совпадает с размером типа времени, поэтому _findfirst64 также поддерживает 64-разрядную длину файлов и _findfirst32 поддерживает только 32-разрядную длину файла.

Эти функции используют различные формы структуры _finddata_t для параметра fileinfo. Дополнительные сведения о структуре см. в функциях поиска имени файла.

Варианты, использующие 64-разрядный тип времени, допускают даты создания файлов до 23:59:59 31-го декабря 3000 года, время в формате UTC. Те, которые используют 32-разрядные типы времени, представляют даты только до 23:59:59 18 января 2038 г. в формате UTC. Полночь 1 января 1970 года — нижняя граница диапазона дат для всех этих функций.

Если нет какой-либо определенной причины использовать версии, указывающие размер времени явно, используйте функцию _findfirst или _wfindfirst или, если необходима поддержка размеров файлов больше 3 ГБ, используйте функцию _findfirsti64 или _wfindfirsti64. Все эти функции используют 64-разрядный тип времени. В более ранних версиях этих функций использовался 32-разрядный тип времени. Если это изменение является критическим изменением для приложения, можно определить_USE_32BIT_TIME_T, чтобы отменить изменения в старое поведение. Если определена директива _USE_32BIT_TIME_T, функции _findfirst, _finfirsti64 и соответствующие версии Юникода используют 32-разрядное время.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Варианты типов времени и типов длины файлов в функции _findfirst

Функции	Директива _USE_32BIT_TIME_T определена?	Тип времени	Тип длины файла
_findfirst, _wfindfirst	Не определено	64-разрядная	32-битная
_findfirst, _wfindfirst	Определено	32-битная	32-битная
_findfirst32, _wfindfirst32	Не затрагивается определением макроса	32-битная	32-битная
_findfirst64, _wfindfirst64	Не затрагивается определением макроса	64-разрядная	64-разрядная
_findfirsti64, _wfindfirsti64	Не определено	64-разрядная	64-разрядная
_findfirsti64, _wfindfirsti64	Определено	32-битная	64-разрядная
_findfirst32i64, _wfindfirst32i64	Не затрагивается определением макроса	32-битная	64-разрядная
_findfirst64i32, _wfindfirst64i32	Не затрагивается определением макроса	64-разрядная	32-битная

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

Tchar.h Обычной	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

Требования

Функция	Обязательный заголовок
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> или <wchar.h>
_wfindfirst32	<io.h> или <wchar.h>
_wfindfirst64	<io.h> или <wchar.h>
_wfindfirsti64	<io.h> или <wchar.h>
_wfindfirst32i64	<io.h> или <wchar.h>
_wfindfirst64i32	<io.h> или <wchar.h>

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

См. также

Системные вызовы
Функции поиска имени файла