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

 

Опубликовано: Июль 2016

Самая актуальная документация по Visual Studio 2017: Документация по Visual Studio 2017.

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

Варианты, использующие 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-разрядное время.

Варианты типов времени и типов длины файлов в функции _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 во введении.

System::IO::DirectoryInfo::GetFiles

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

Показ: