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

Статья
06/02/2023

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

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

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

Синтаксис

HANDLE FindFirstFileW(
  [in]  LPCWSTR            lpFileName,
  [out] LPWIN32_FIND_DATAW 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.

Как было сказано ранее, вы не можете использовать обратную косую черту в конце (\) во входной строке lpFile для 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	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
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]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll