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）。
搜尋包含長和短檔名。
嘗試開啟具有尾端反斜杠的搜尋一律會失敗。
傳遞無效的字串、NULL或 lpFileName 參數的空字串，不是這個函式的有效用法。在此情況下，結果為未定義。

注意在極少數情況下或在大量載入的系統上，在呼叫此函式時，NTFS 檔案系統上的檔案屬性資訊可能不是最新的。若要確保取得目前的NTFS檔系統檔案屬性，請呼叫 getFileInformationByHandle 函式。

建立搜尋句柄之後，您可以使用它來搜尋其他符合相同模式的檔案，方法是使用 FindNextFile 函式。

不再需要搜尋句柄時，請使用 FindClose 函式關閉它，而不是 CloseHandle。

如先前所述，您無法在 lpFileName 輸入字串中使用尾端反斜杠（\）， FindFirstFile，因此搜尋根目錄可能並不明顯。如果您想要檢視檔案或取得根目錄的屬性，適用下列選項：

若要檢查根目錄中的檔案，您可以使用「C：\*」，並使用 FindNextFile逐步執行目錄。
若要取得根目錄的屬性，請使用 GetFileAttributes 函式。

附註在字串 “\\？\” 前面，不允許存取根目錄。

在網路共用上，您可以使用 lpFileName，格式如下：“\\Server\Share\*”。不過，您無法使用指向共用本身的 lpFileName;例如，“\\Server\Share” 無效。

若要檢查不是根目錄的目錄，請使用該目錄的路徑，而不需要尾端反斜杠。例如，“C：\Windows” 的自變數會傳回目錄 “C：\Windows” 的相關信息，而不是 “C：\Windows” 中的目錄或檔案。若要檢查「C：\Windows」中的檔案和目錄，請使用 “C：\Windows\*” 的 lpFileName。

請注意，一些其他線程或進程可以在您查詢結果與處理信息的時間之間，建立或刪除具有此名稱的檔案。如果這是應用程式的潛在問題，其中一個可能的解決方案是使用 CreateFile 函式搭配 CREATE_NEW （如果檔案存在則失敗）或 OPEN_EXISTING （如果檔案不存在則失敗）。

如果您要撰寫 32 位應用程式來列出目錄中的所有檔案，而且應用程式可能會在 64 位電腦上執行，您應該先呼叫 Wow64DisableWow64FsRedirection 函式，再呼叫 findFirstFile，並在最後一次呼叫 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 預處理器常數的定義，將 FindFirstFile 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	fileapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll