FindFirstFileA 関数 (fileapi.h)

  • [アーティクル]

指定した名前 (または、ワイルドカードが使用されている場合は部分名) と一致する名前のファイルやサブディレクトリをディレクトリで検索します。

検索で使用する追加の属性を指定するには、 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」を参照してください)。
  • 検索には、長いファイル名と短いファイル名が含まれます。
  • 末尾の円記号を使用して検索を開こうとすると、常に失敗します。
  • lpFileName パラメーターに無効な文字列、NULL、または空の文字列を渡すことは、この関数の有効な使用ではありません。 この場合の結果は未定義です。
メモ まれに、または負荷の高いシステムでは、この関数が呼び出された時点で NTFS ファイル システムのファイル属性情報が最新ではない可能性があります。 現在の NTFS ファイル システム ファイル属性を確実に取得するには、 GetFileInformationByHandle 関数を呼び出します。
 
検索ハンドルが確立されたら、 FindNextFile 関数を使用して、同じパターンに一致する他のファイルを検索できます。

検索ハンドルが不要になったら、CloseHandle ではなく FindClose 関数を使用して閉じます。

前に説明したように、FindFirstFile の lpFileName 入力文字列で末尾の円記号 (\) を使用することはできないため、ルート ディレクトリの検索方法が明確でない可能性があります。 ファイルを表示したり、ルート ディレクトリの属性を取得したりする場合は、次のオプションが適用されます。

  • ルート ディレクトリ内のファイルを調べるには、"C:\*" を使用し、 FindNextFile を使用してディレクトリをステップ実行します。
  • ルート ディレクトリの属性を取得するには、 GetFileAttributes 関数を 使用します。
メモ 文字列 "\\?\" をプリペンドしても、ルート ディレクトリへのアクセスは許可されません。
 

ネットワーク共有では、 lpFileName を "\\Server\Share\*" の形式で使用できます。 ただし、共有自体を指す lpFileName を使用することはできません。たとえば、"\\Server\Share" は無効です。

ルート ディレクトリではないディレクトリを調べるには、末尾の円記号を使用せずに、そのディレクトリへのパスを使用します。 たとえば、"C:\Windows" の引数は、"C:\Windows" のディレクトリまたはファイルではなく、ディレクトリ "C:\Windows" に関する情報を返します。 "C:\Windows" のファイルとディレクトリを調べるには、"C:\Windows\*" の lpFileName を使用します。

他のスレッドまたはプロセスでは、結果のクエリを実行してから情報に基づいて処理する時間の間に、この名前のファイルが作成または削除される可能性があることに注意してください。 これがアプリケーションの潜在的な懸念事項である場合、考えられる解決策の 1 つは、 createFile 関数を CREATE_NEW (ファイルが存在する場合は失敗) または OPEN_EXISTING (ファイルが存在しない場合は失敗) と共に使用することです。

ディレクトリ内のすべてのファイルを一覧表示する 32 ビット アプリケーションを作成していて、アプリケーションが 64 ビット コンピューターで実行される可能性がある場合は、FindFirstFile を呼び出す前に Wow64DisableWow64FsRedirection 関数を呼び出し、FindNextFile の最後の呼び出しの後に Wow64RevertWow64FsRedirection を呼び出す必要があります。 詳細については、「 ファイル システム リダイレクター」を参照してください。

パスがシンボリック リンクを指している場合、WIN32_FIND_DATA バッファーにはターゲットではなくシンボリック リンクの情報が含まれます。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (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 ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして FindFirstFile を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー fileapi.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

File Management 関数

FindClose

FindFirstFileEx

FindFirstFileTransacted

FindNextFile

GetFileAttributes

SetFileAttributes

シンボリック リンク

Windows ヘッダーの使用

WIN32_FIND_DATA