_findfirst, _wfindfirst

Статья
06/09/2015

Предоставить сведения о первом экземпляре имени файла, соответствующему файлу, указанному в аргументе 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 одно из следующих значений.

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

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

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

Заметки

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

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

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

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

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

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

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

Функции	Определен ли _USE_32BIT_TIME_T?	Тип Time.	Тип File length
_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>