Поделиться через


_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
Буфер сведений о файле. Дополнительные сведения о структуре см. в разделе "Примечания" 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-разрядные типы времени и размеры файлов, см. в следующей таблице. Или i32 i64 суффикс опущен, если он совпадает с размером типа времени, поэтому _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, _findfirsti64 и соответствующие версии Юникода используют 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

Требования

Function Обязательный заголовок
_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>

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

См. также

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