_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64

提供檔名第一個執行個體的資訊，此檔名與 filespec 引數中所指定的檔案相符。

語法

intptr_t _findfirst(
   const char *filespec,
   struct _finddata_t *fileinfo
);
intptr_t _findfirst32(
   const char *filespec,
   struct _finddata32_t *fileinfo
);
intptr_t _findfirst64(
   const char *filespec,
   struct _finddata64_t *fileinfo
);
intptr_t _findfirsti64(
   const char *filespec,
   struct _finddatai64_t *fileinfo
);
intptr_t _findfirst32i64(
   const char *filespec,
   struct _finddata32i64_t *fileinfo
);
intptr_t _findfirst64i32(
   const char *filespec,
   struct _finddata64i32_t *fileinfo
);
intptr_t _wfindfirst(
   const wchar_t *filespec,
   struct _wfinddata_t *fileinfo
);
intptr_t _wfindfirst32(
   const wchar_t *filespec,
   struct _wfinddata32_t *fileinfo
);
intptr_t _wfindfirst64(
   const wchar_t *filespec,
   struct _wfinddata64_t *fileinfo
);
intptr_t _wfindfirsti64(
   const wchar_t *filespec,
   struct _wfinddatai64_t *fileinfo
);
intptr_t _wfindfirst32i64(
   const wchar_t *filespec,
   struct _wfinddata32i64_t *fileinfo
);
intptr_t _wfindfirst64i32(
   const wchar_t *filespec,
   struct _wfinddata64i32_t *fileinfo
);

參數

filespec
目標檔案規格 (可以包含萬用字元)。

fileinfo
檔案資訊緩衝區。

傳回值

如果成功， _findfirst 會傳回唯一的搜尋控制碼，識別符合 filespec 規格的檔案或檔案群組，這可用於後續對 _findnext 或 _findclose 的呼叫。 否則， _findfirst 會傳回 -1，並將 設定 errno 為下列其中一個值。

errno 值	條件
EINVAL	參數無效：filespec 或 fileinfo 是 NULL。 或者，作業系統傳回未預期的錯誤。
ENOENT	無法比對的檔案規格。
ENOMEM	記憶體不足。
EINVAL	檔名規格無效，或指定的檔名大於 MAX_PATH。

如需這些傳回碼和其他傳回碼的詳細資訊，請參閱 errno 、 _sys_errlist_doserrno 和 _sys_nerr 。

如果傳入不正確參數，這些函式會叫用不正確參數處理常式，如參數驗證 中所述 。

備註

您必須在完成 _findfirst 或 _findnext 函式之後呼叫 _findclose ，或 函式（或任何變體）提供成功 _findfirst 呼叫。 _findclose 釋放應用程式中這些函式所使用的資源。 在不正確控制碼上呼叫 _findclose 會傳 -1 回 ，並將 設定 errno 為 EINVAL 。

具有 w 前置詞的這些函式的變化是寬字元版本;否則，它們與對應的單一位元組函式相同。

這些函式的變化支援 32 位元或 64 位元時間類型，以及 32 位元或 64 位元檔案大小。 第一個數值尾碼 (32 或 64) 表示時間類型的大小；第二個尾碼為 i32 或 i64，並且表示檔案大小是以 32 位元還是 64 位元整數表示。 如需支援 32 位元和 64 位元時間類型與檔案大小之版本的資訊，請參閱下表。 i32如果 或 尾碼與時間類型的大小相同，則省略 或 i64 尾碼，因此 _findfirst64 也支援 64 位檔案長度，且 _findfirst32 僅支援 32 位檔案長度。

這些函式針對 fileinfo 參數使用各種形式的 _finddata_t 結構。 如需 結構的詳細資訊，請參閱 檔案名搜尋函式 。

使用 64 位元時間類型的變化可將檔案建立日期最高表示為 3000 年 12 月 31 日 23:59:59 UTC。 使用 32 位時間類型的日期，僅代表 2038 年 1 月 18 日 23：59：59、UTC。 1970 年 1 月 1 日午夜是所有這些函式的日期範圍下限。

除非您有特定原因要使用明確指定時間大小的版本，否則請使用 _findfirst 或 _wfindfirst，或者，如果您需要支援大於 3 GB 的檔案大小，請使用 _findfirsti64 或 _wfindfirsti64。 所有這些函式都使用 64 位元時間類型。 在舊版本中，這些函式都是使用 32 位元時間類型。 如果這項變更是應用程式的中斷性變更，您可能會定義 _USE_32BIT_TIME_T 還原成舊的行為。 如果定義 _USE_32BIT_TIME_T，_findfirst、_finfirsti64 和其對應的 Unicode 版本會使用 32 位元時間。

根據預設，此函式的全域狀態會限定于應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

_findfirst 的時間類型和檔案長度類型變化

函式	已定義 _USE_32BIT_TIME_T 嗎？	時間類型	檔案長度類型
_findfirst, _wfindfirst	未定義	64 位元	32 位元
_findfirst, _wfindfirst	已定義	32 位元	32 位元
_findfirst32, _wfindfirst32	不會受到巨集定義的影響	32 位元	32 位元
_findfirst64, _wfindfirst64	不會受到巨集定義的影響	64 位元	64 位元
_findfirsti64, _wfindfirsti64	未定義	64 位元	64 位元
_findfirsti64, _wfindfirsti64	已定義	32 位元	64 位元
_findfirst32i64, _wfindfirst32i64	不會受到巨集定義的影響	32 位元	64 位元
_findfirst64i32, _wfindfirst64i32	不會受到巨集定義的影響	64 位元	32 位元

泛型文字常式對應

Tchar.h 常規	_UNICODE 和 _MBCS 未定義	_MBCS 定義	_UNICODE 定義
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

需求

函式	必要的標頭
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> 或 <wchar.h>
_wfindfirst32	<io.h> 或 <wchar.h>
_wfindfirst64	<io.h> 或 <wchar.h>
_wfindfirsti64	<io.h> 或 <wchar.h>
_wfindfirst32i64	<io.h> 或 <wchar.h>
_wfindfirst64i32	<io.h> 或 <wchar.h>

如需相容性詳細資訊，請參閱相容性。

另請參閱

系統呼叫
檔案名搜尋函式