FindFirstFileW 関数 (fileapi.h)

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

検索で使用する追加の属性を指定するには、 FindFirstFileEx 関数を使用します。

この操作をトランザクション操作として実行するには、 FindFirstFileTransacted 関数を使用します。

構文

HANDLE FindFirstFileW(
  [in]  LPCWSTR            lpFileName,
  [out] LPWIN32_FIND_DATAW lpFindFileData
);

パラメーター

[in] lpFileName

ディレクトリまたはパス、およびファイル名。 ファイル名には、アスタリスク (*) や疑問符 (?) などのワイルドカード文字を含めることができます。

このパラメーターは 、NULL、無効な文字列 (空の文字列、終端の null 文字がない文字列など)、末尾の円記号 (\) で終わる値にすることはできません。

文字列がワイルドカード、ピリオド (.)、またはディレクトリ名で終わる場合、ユーザーはルートとパス上のすべてのサブディレクトリへのアクセス許可を持っている必要があります。

この関数の ANSI バージョンでは、名前は MAX_PATH 文字に制限されています。 この制限を 32,767 文字まで拡張するには、Unicode バージョンの関数を呼び出し、パスに "\\?\" を付加します。 詳細については、「 ファイルの名前付け」を参照してください。

ヒントバージョン 1607 Windows 10以降、この関数の Unicode バージョン (FindFirstFileW) の場合、事前の "\\\\" なしで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 関数を使用して閉じます。

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

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

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

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

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

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

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

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

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有を含む SMB 3.0 (SO) はい
クラスター共有ボリューム ファイル システム (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 を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

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

関連項目

ファイル管理機能

FindClose

FindFirstFileEx

FindFirstFileTransacted

FindNextFile

GetFileAttributes

SetFileAttributes

シンボリック リンク

Windows ヘッダーの使用

WIN32_FIND_DATA