指定されたファイル名に一致するファイルを、ディレクトリ内で検索します。ファイル名だけでなく、サブディレクトリ名も検索の対象となります。

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

HANDLE FindFirstFile(
  LPCTSTR lpFileName,               // ファイル名
  LPWIN32_FIND_DATA lpFindFileData  // データバッファ
);

パラメータ

lpFileName

有効なディレクトリ名、またはパス名とファイル名を保持している、NULL で終わる文字列へのポインタを指定します。この文字列に「*」または「?」のワイルドカード文字を含めることができます。

Windows NT/2000：この関数の ANSI 版では、名前は最大 MAX_PATH 文字に制限されています。この制限をほぼ 32,000 ワイド文字へ拡張するには、この関数の Unicode 版を呼び出し、パスの前に "\\?\" という接頭辞を追加してください。詳細については、MSDN ライブラリの「」（ファイル名の規則）を参照してください。

Windows 95/98：文字列の長さは、最大 MAX_PATH 文字です。

lpFindFileData

1 個の 構造体へのポインタを指定します。関数から制御が返ると、この構造体に、見つかったファイル（またはサブディレクトリ）に関する情報が格納されます。

戻り値

関数が成功すると、検索ハンドルが返ります。この検索ハンドルは、それ以降の FindNextFile 関数や FindClose 関数で使います。

関数が失敗すると、INVALID_HANDLE_VALUE が返ります。拡張エラー情報を取得するには、 関数を使います。

解説

FindFirstFile 関数は、検索ハンドルを開き、指定されたパターンと一致する名前を持つ最初のファイルに関する情報を返します。その後、この検索ハンドルを FindNextFile 関数に渡すと、指定されたパターンに一致するほかのファイルを検索できます。検索ハンドルが不要になったら、FindClose 関数を呼び出して閉じてください。

この関数は、名前のみによる検索を行います。属性による検索はできません。

FindFirstFile の lpFileName パラメータでは、最後に円記号（\）を付けるかどうかにかかわりなく、ルートディレクトリを指定することはできません。ルートディレクトリ内のファイルを検索するには、この関数で "C:\*" のようなファイル名を指定し、引き続き GetFileAttributes 関数を使ってルートディレクトリ内を検索してください。ルートディレクトリの属性を取得するには、GetFileAttributes 関数を使います。文字列の前に "\\?\" という接頭辞を追加すると、ルートディレクトリにアクセスできなくなります。

同様に、ネットワーク共有を検索するために、lpFileName パラメータで "\\server\service\*" という形式を指定できます。しかし、"\\server\service" のように共有自体を指す文字列を lpFileName パラメータで指定することはできません。

ルートディレクトリ以外のディレクトリを検索するには、そのディレクトリを指す適切なパス名を指定し、最後の円記号（\）を付けないでください。たとえば、"C:\windows" という文字列を指定すると、そのディレクトリ内のファイルやサブディレクトリに関する情報ではなく、そのディレクトリに関する情報を取得できます。最後の円記号をつけて検索を行おうとすると、必ずこの関数は失敗します。

MAPI：詳細については、MSDN ライブラリの「」を参照してください。

次のサンプルコードは、FindFirstFile の最も簡単な使い方を示します。

#define _WIN32_WINNT 0x0400

#include "windows.h"

int

main(int argc, char *argv[])

{

  WIN32_FIND_DATA FindFileData;

  HANDLE hFind;

  printf ("Target file is %s.\n", argv[1]);

  hFind = FindFirstFile(argv[1], &FindFileData);

  if (hFind == INVALID_HANDLE_VALUE) {

    printf ("Invalid File Handle. Get Last Error reports %d\n", GetLastError ());

  } else {

    printf ("The first file found is %s\n", FindFileData.cFileName);

    FindClose(hFind);

  }

  return (0);

}

対応情報

Windows NT/2000：Windows NT 3.1 以降
Windows 95/98：Windows 95 以降
ヘッダー：Winbase.h 内で宣言、Windows.h をインクルード
インポートライブラリ：Kernel32.lib を使用
Unicode：Windows NT/2000 は Unicode 版と ANSI 版を実装

参照

FindClose, FindFirstFileEx, FindNextFile, GetFileAttributes, SetFileAttributes,