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を参照してください)。
検索には、長いファイル名と短いファイル名が含まれます。
末尾の円記号を使用して検索を開こうとすると、常に失敗します。
lpFileName パラメーターに無効な文字列、NULL、または空の文字列を渡すことは、この関数の有効な使用ではありません。この場合の結果は未定義です。

注まれなケースや負荷の高いシステムでは、この関数が呼び出された時点で NTFS ファイルシステムのファイル属性情報が最新でない可能性があります。現在の NTFS ファイルシステムファイル属性を確実に取得するには、GetFileInformationByHandle 関数を呼び出します。

検索ハンドルが確立されたら、FindNextFile 関数を使用して、同じパターンに一致する他のファイルを検索できます。

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

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

ルートディレクトリ内のファイルを調べるには、"C:\*" を使用し、FindNextFileを使用してディレクトリをステップ実行できます。
ルートディレクトリの属性を取得するには、GetFileAttributes 関数を使用します。

メモ文字列 "\\?\" はルートディレクトリへのアクセスを許可しません。

ネットワーク共有では、"\\Server\Share\*" の形式で lpFileName を使用できます。ただし、共有自体を指す 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 透過的フェールオーバー (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 ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして FindFirstFile を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	fileapi.h (Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

FindFirstFileA 関数 (fileapi.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース