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

Статья
11/20/2024

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

Чтобы указать дополнительные атрибуты для использования в поиске, используйте функцию 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 CreateFile с CREATE_NEW (которая завершается ошибкой, если файл существует) или OPEN_EXISTING (который завершается ошибкой, если файл не существует).

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

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

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

Технологии	Поддержанный
Протокол SMB 3.0	Да
Отработка отказа SMB 3.0 (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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll