_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> |
Дополнительные сведения о совместимости см. в разделе Совместимость.