_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 Условие
EINVAL Недопустимый параметр: filespec или fileinfo имеет значение NULL. Или операционная система возвратила непредвиденную ошибку.
ENOENT Спецификация файла, которую не удалось сопоставить.
ENOMEM Недостаточно памяти.
EINVAL Недопустимая спецификация имени файла или длина заданного имени файла больше MAX_PATH.

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

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

Комментарии

После завершения _findfirst работы с функцией или _findnext функцией (или любыми вариантами) необходимо вызвать вызов_findclose. _findclose освобождает ресурсы, используемые этими функциями в приложении.

Варианты этих функций с 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>

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

См. также раздел

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