_findfirst， _wfindfirst

项目
02/21/2013

提供有关与 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 为下列值之一。

EINVAL
无效参数: filespec 或 fileinfo 是 NULL。或者，操作系统会返回意外的错误。
ENOENT
不能匹配的文件规范。
ENOMEM
内存不足。
EINVAL
无效文件名指定或退出的文件名大于 MAX_PATH。

有关这些属性和其他的更多信息返回代码示例，请参见 _doserrno、 errno、 _sys_errlist 和 _sys_nerr。

如果一个传递的参数无效，这些函数调用的参数无效处理程序，如参数验证所述。

备注

必须调用 _findclose ，在使用完毕后 _findfirst 或 _findnext 函数后 (或任何变量)。这将释放这些功能使用的资源在应用程序。

具有 w 标题这些功能的变化是宽字符版本;否则，它们与对应的单字节功能是相同的。

这些功能的变体支持 32 位或 64 位时类型和 32 位或 64 位文件大小。第一个数字后缀 (32 或 64) 指示时类型的大小;第二后缀是 i32 或 i64，并指示文件大小是否表示为 32 位或 64 位整数。有关哪些信息版本支持 32 位和 64 位时间类型以及文件大小，请参见下表。 i32 或 i64 后缀省略，如果它与时间类型的范围，因此， _findfirst64 还支持 64 位文件长度，并 _findfirst32 仅支持 32 位文件长度。

这些功能为 fileinfo 参数使用多种多样 _finddata_t 结构。有关结构的更多信息，请参见 _find， _wfind功能。

使用 64 位时类型的变体使文件创建日期。 23:59 表示: 59， 3000 年十二月 31 日，， UTC。使用 32 位时类型的那些下午 19:14 仅表示日期: 一月 07 日 18 日 2038 中， UTC。午夜， 1970 年一月 1 日，是日期范围的下限所有这些功能。

除非您具有特定原因需要使用显式指定时间范围的版本中，使用 _findfirst 或 _wfindfirst ，或者，如果需要支持文件大小超过 3 GB，使用 _findfirsti64 或 _wfindfirsti64。所有这些函数使用 64 位时类型。在早期版本中，这些函数使用了 32 位时类型。如果这是应用程序的重大更改，可以定义 _USE_32BIT_TIME_T 还原为旧行为。如果 _USE_32BIT_TIME_T 定义， _findfirst、 _finfirsti64及其对应的 Unicode 版本使用 32 位时间。

超时 _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