Функция FindFirstFileA (fileapi.h)

Статья
06/02/2023

Выполняет поиск в каталоге файла или подкаталога с именем, которое соответствует определенному имени (или частичному имени, если используются подстановочные знаки).

Чтобы указать дополнительные атрибуты для поиска, используйте функцию FindFirstFileEx .

Чтобы выполнить эту операцию как транзакцию, используйте функцию FindFirstFileTransacted .

Синтаксис

HANDLE FindFirstFileA(
  [in]  LPCSTR             lpFileName,
  [out] LPWIN32_FIND_DATAA lpFindFileData
);

Параметры

[in] lpFileName

Каталог или путь, а также имя файла. Имя файла может содержать подстановочные знаки, например звездочку (*) или вопросительный знак (?).

Этот параметр не должен иметь значение NULL, недопустимую строку (например, пустую строку или строку, в которую отсутствует завершающий символ NULL) или заканчиваться обратной косой чертой (\).

Если строка заканчивается подстановочным знаком, точкой (.) или именем каталога, пользователь должен иметь разрешения на доступ к корневому каталогу и всем подкаталогам по пути.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления в начало "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

[out] lpFindFileData

Указатель на структуру WIN32_FIND_DATA , которая получает сведения об найденном файле или каталоге.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение представляет собой дескриптор поиска, используемый при последующем вызове FindNextFile или FindClose, а параметр lpFindFileData содержит сведения о первом найденном файле или каталоге.

Если функции не удается найти файлы из строки поиска в параметре lpFileName , возвращаемое значение будет INVALID_HANDLE_VALUE а содержимое lpFindFileData не определено. Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .

Если функция завершается сбоем из-за отсутствия соответствующих файлов, функция GetLastError возвращает ERROR_FILE_NOT_FOUND.

Функция FindFirstFile открывает дескриптор поиска и возвращает сведения о первом файле, найденном файловой системой, с именем, соответствующим указанному шаблону. Это может быть или не первый файл или каталог, который отображается в приложении со списком каталогов (например, команда dir), если задан тот же шаблон строки имени файла. Это связано с тем, что FindFirstFile не сортирует результаты поиска. Дополнительные сведения см. в разделе FindNextFile.

В следующем списке указаны некоторые другие характеристики поиска:

Поиск выполняется исключительно по имени файла, а не по каким-либо атрибутам, таким как дата или тип файла (другие параметры см. в разделе FindFirstFileEx).
Поиск включает длинные и короткие имена файлов.
Попытка открыть поиск с конечной обратной косой чертой всегда завершается неудачей.
Передача недопустимой строки, NULL или пустой строки для параметра lpFileName не является допустимым использованием этой функции. В этом случае результаты не определены.

Примечание В редких случаях или в сильно загруженной системе сведения об атрибутах файлов в файловых системах NTFS могут быть не актуальными на момент вызова этой функции. Чтобы получить текущие атрибуты файловой системы NTFS, вызовите функцию GetFileInformationByHandle .

После установки дескриптора поиска его можно использовать для поиска других файлов, соответствующих тому же шаблону, с помощью функции FindNextFile .

Если дескриптор поиска больше не нужен, закройте его с помощью функции FindClose , а не CloseHandle.

Как упоминалось ранее, вы не можете использовать обратную косую черту в конце (\) во входной строке lpFileName для FindFirstFile, поэтому поиск в корневых каталогах может быть неочевидным. Если вы хотите просмотреть файлы или получить атрибуты корневого каталога, применяются следующие параметры:

Чтобы изучить файлы в корневом каталоге, можно использовать "C:\*" и выполнить пошаговое выполнение каталога с помощью FindNextFile.
Чтобы получить атрибуты корневого каталога, используйте функцию GetFileAttributes .

Примечание При добавлении строки "\\?\" не разрешен доступ к корневому каталогу.

В сетевых ресурсах можно использовать lpFileName в следующем виде: "\\Server\Share\*". Однако нельзя использовать lpFileName , указывающее на сам общий ресурс; Например, недопустимый параметр \\Server\Share.

Чтобы проверить каталог, который не является корневым, используйте путь к нему без обратной косой черты в конце. Например, аргумент "C:\Windows" возвращает сведения о каталоге "C:\Windows", а не о каталоге или файле в "C:\Windows". Чтобы изучить файлы и каталоги в "C:\Windows", используйте lpFileName "C:\Windows\*".

Имейте в виду, что некоторые другие потоки или процессы могут создавать или удалять файл с таким именем между временем запроса результата и временем выполнения действий с данными. Если это потенциальная проблема для приложения, можно использовать функцию CreateFile с CREATE_NEW (которая завершается сбоем, если файл существует) или OPEN_EXISTING (если файл не существует).

Если вы пишете 32-разрядное приложение для перечисления всех файлов в каталоге и приложение может быть запущено на 64-разрядном компьютере, следует вызвать функцию Wow64DisableWow64FsRedirection перед вызовом FindFirstFile и вызвать Wow64RevertWow64FsRedirection после последнего вызова FindNextFile. Дополнительные сведения см. в разделе Перенаправитель файловой системы.

Если путь указывает на символьную ссылку, буфер WIN32_FIND_DATA содержит сведения о символьной ссылке, а не целевой объект.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

В следующем примере C++ показано минимальное использование FindFirstFile.

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFile(argv[1], &FindFileData);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFile failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Другой пример см. в разделе Перечисление файлов в каталоге.

Примечание

Заголовок fileapi.h определяет FindFirstFile в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll