文件名搜索函数Filename Search Functions

这些函数搜索并关闭搜索指定的文件名称:These functions search for and close searches for specified file names:

备注Remarks

_findfirst 函数提供与 filespec 参数中指定的文件匹配的文件名的第一个实例的有关信息。The _findfirst function provides information about the first instance of a file name that matches the file specified in the filespec argument. 可以在 filespec 中使用主机操作系统支持的通配符字符的任意组合。You can use in filespec any combination of wildcard characters that is supported by the host operating system.

函数返回在 IO.h. 中定义的 _finddata_t 结构中的文件信息。The functions return file information in a _finddata_t structure, which is defined in IO.h. 系列中的各种函数上使用许多不同 _finddata_t 结构。Various functions in the family use many variations on the _finddata_t structure. 基本 _finddata_t 结构包含以下元素:The basic _finddata_t structure includes the following elements:

unsigned attrib
文件属性。File attribute.

time_t time_create
文件的创建时间(对于 FAT 文件系统为 -1L)。Time of file creation (-1L for FAT file systems). 该时间以 UTC 格式存储。This time is stored in UTC format. 若要转换为本地时间,请使用 localtime_sTo convert to the local time, use localtime_s.

time_t time_access
文件的上次访问时间(对于 FAT 文件系统为 -1L)。Time of the last file access (-1L for FAT file systems). 该时间以 UTC 格式存储。This time is stored in UTC format. 若要转换为本地时间,请使用 localtime_sTo convert to the local time, use localtime_s.

time_t time_write
文件的上次写入时间。Time of the last write to file. 该时间以 UTC 格式存储。This time is stored in UTC format. 若要转换为本地时间,请使用 localtime_sTo convert to the local time, use localtime_s.

_fsize_t size
文件的长度(以字节为单位)。Length of the file in bytes.

char name[ _MAX_PATH]char name[ _MAX_PATH]
匹配的文件或目录(不含路径)的以 null 结尾的名称。Null-terminated name of matched file or directory, without the path.

在不支持文件的创建时间和上次访问时间的文件系统中(例如 FAT 系统), time_createtime_access 字段始终为 -1L。In file systems that do not support the creation and last access times of a file, such as the FAT system, the time_create and time_access fields are always -1L.

_MAX_PATH 在 Stdlib.h 中定义为 260 个字节。_MAX_PATH is defined in Stdlib.h as 260 bytes.

不能指定目标属性(如 _A_RDONLY来限制执行查找操作。You cannot specify target attributes (such as _A_RDONLY) to limit the find operation. 这些属性在 attrib 结构的 _finddata_t 字段中返回,并且可能具有以下值(在 IO.h 中定义)。These attributes are returned in the attrib field of the _finddata_t structure and can have the following values (defined in IO.h). 用户不应依赖可能为 attrib 字段中的唯一值的这些值。Users should not rely on these being the only values possible for the attrib field.

_A_ARCH
存档。Archive. 每当通过 BACKUP 命令更改或清除文件时进行设置。Set whenever the file is changed and cleared by the BACKUP command. 值:0x20。Value: 0x20.

_A_HIDDEN
隐藏文件。Hidden file. 使用 DIR 命令时通常不可见,除非使用 /AH 选项。Not generally seen with the DIR command, unless you use the /AH option. 返回普通文件和具有此属性的文件的相关信息。Returns information about normal files and files that have this attribute. 值:0x02。Value: 0x02.

_A_NORMAL
正常。Normal. 文件未设置其他属性,可不受限制地读取或写入文件。File has no other attributes set and can be read or written to without restriction. 值:0x00。Value: 0x00.

_A_RDONLY
只读。Read-only. 无法打开文件进行写入且无法创建具有相同名称的文件。File cannot be opened for writing and a file that has the same name cannot be created. 值:0x01。Value: 0x01.

_A_SUBDIR
子目录。Subdirectory. 值:0x10。Value: 0x10.

_A_SYSTEM
系统文件。System file. 使用 DIR 命令时通常不可见,除非使用 /A/A:S 选项。Not ordinarily seen with the DIR command, unless the /A or /A:S option is used. 值:0x04。Value: 0x04.

_findnext 找到下一个名称(若有),该名称匹配对 filespec 的早期调用中指定的 _findfirst参数。_findnext finds the next name, if any, that matches the filespec argument specified in an earlier call to _findfirst. fileinfo 参数应指向由之前对 _findfirst的调用初始化的结构。The fileinfo argument should point to a structure initialized by the previous call to _findfirst. 如果找到匹配项,则如前文所述, fileinfo 结构内容将发生更改。If a match is found, the fileinfo structure contents are changed as described earlier. 否则保持不变。Otherwise, it is left unchanged. _findclose 关闭指定的搜索句柄并释放 _findfirst_findnext的所有关联资源。_findclose closes the specified search handle and releases all associated resources for both _findfirst and _findnext. 通过 _findfirst_findnext 返回的句柄必须首先传递给 _findclose,然后才对形成传递路径的目录执行修改操作(例如删除)。The handle returned by either _findfirst or _findnext must first be passed to _findclose, before modification operations, such as deleting, can be performed on the directories that form the paths passed to them.

你可以嵌套 _find 函数。You can nest the _find functions. 例如,如果对 _findfirst_findnext 的调用找到作为子目录的文件,则可以使用对 _findfirst_findnext的另一个调用开始新的搜索。For example, if a call to _findfirst or _findnext finds the file that is a subdirectory, a new search can be initiated with another call to _findfirst or _findnext.

_wfindfirst_wfindnext_findfirst_findnext的宽字符版本。_wfindfirst and _wfindnext are wide-character versions of _findfirst and _findnext. 宽字符版本的结构参数具有在 IO.h 和 Wchar.h 中定义的 _wfinddata_t 数据类型。The structure argument of the wide-character versions has the _wfinddata_t data type, which is defined in IO.h and in Wchar.h. 该数据类型的字段与 _finddata_t 数据类型中的相同,除非在 _wfinddata_t 中,名称字段属于 wchar_t 类型,而不属于 char类型。The fields of this data type are the same as those of the _finddata_t data type, except that in _wfinddata_t the name field is of type wchar_t instead of type char. 除此之外, _wfindfirst_wfindnext 的行为与 _findfirst_findnext完全相同。Otherwise _wfindfirst and _wfindnext behave identically to _findfirst and _findnext.

_findfirst_findnext 使用 64 位时间类型。_findfirst and _findnext use the 64-bit time type. 如果你必须使用旧的 32 位时间类型,则可以定义 _USE_32BIT_TIME_TIf you must use the old 32-bit time type, you can define _USE_32BIT_TIME_T. 名称中具有 32 后缀的这些函数的版本使用 32 位时间类型,而具有 64 后缀的那些版本使用 64 位时间类型。The versions of these functions that have the 32 suffix in their names use the 32-bit time type, and those with the 64 suffix use the 64-bit time type.

除了使用并返回 64 位文件长度外,函数 _findfirst32i64_findnext32i64``_wfindfirst32i64_wfindnext32i64 的行为与 32 位时间类型版本的这些函数相同。Functions _findfirst32i64, _findnext32i64, _wfindfirst32i64, and _wfindnext32i64 also behave identically to the 32-bit time type versions of these functions except they use and return 64-bit file lengths. 函数 _findfirst64i32_findnext64i32_wfindfirst64i32_wfindnext64i32 使用 64 位时间类型,但使用 32 位文件长度。Functions _findfirst64i32, _findnext64i32, _wfindfirst64i32, and _wfindnext64i32 use the 64-bit time type but use 32-bit file lengths. 这些函数使用适当 _finddata_t 类型变体,其中字段对于时间和文件大小具有不同的类型。These functions use appropriate variations of the _finddata_t type in which the fields have different types for the time and the file size.

_finddata_t 实际上是计算结果为 _finddata64i32_t 的宏(或如果定义了 _finddata32_t ,则为 _USE_32BIT_TIME_T )。_finddata_t is actually a macro that evaluates to _finddata64i32_t (or _finddata32_t if _USE_32BIT_TIME_T is defined). 下表总结了 _finddata_t上的变体:The following table summarizes the variations on _finddata_t:

结构Structure 时间类型Time type 文件大小类型File size type
_finddata_t, _wfinddata_t_finddata_t, _wfinddata_t __time64_t _fsize_t
_finddata32_t, _wfinddata32_t_finddata32_t, _wfinddata32_t __time32_t _fsize_t
__finddata64_t, __wfinddata64_t__finddata64_t, __wfinddata64_t __time64_t __int64
_finddata32i64_t, _wfinddata32i64_t_finddata32i64_t, _wfinddata32i64_t __time32_t __int64
_finddata64i32_t, _wfinddata64i32_t_finddata64i32_t, _wfinddata64i32_t __time64_t _fsize_t

_fsize_tunsigned longtypedef(32 位)。_fsize_t is a typedef for unsigned long (32 bits).

示例Example

// crt_find.c  
// This program uses the 32-bit _find functions to print  
// a list of all files (and their attributes) with a .C extension  
// in the current directory.  

#include <stdio.h>  
#include <stdlib.h>  
#include <io.h>  
#include <time.h>  

int main( void )  
{  
   struct _finddata_t c_file;  
   intptr_t hFile;  

   // Find first .c file in current directory   
   if( (hFile = _findfirst( "*.c", &c_file )) == -1L )  
      printf( "No *.c files in current directory!\n" );  
   else  
   {  
      printf( "Listing of .c files\n\n" );  
      printf( "RDO HID SYS ARC  FILE         DATE %25c SIZE\n", ' ' );  
      printf( "--- --- --- ---  ----         ---- %25c ----\n", ' ' );  
      do {  
         char buffer[30];  
         printf( ( c_file.attrib & _A_RDONLY ) ? " Y  " : " N  " );  
         printf( ( c_file.attrib & _A_HIDDEN ) ? " Y  " : " N  " );  
         printf( ( c_file.attrib & _A_SYSTEM ) ? " Y  " : " N  " );  
         printf( ( c_file.attrib & _A_ARCH )   ? " Y  " : " N  " );  
         ctime_s( buffer, _countof(buffer), &c_file.time_write );  
         printf( " %-12s %.24s  %9ld\n",  
            c_file.name, buffer, c_file.size );  
      } while( _findnext( hFile, &c_file ) == 0 );  
      _findclose( hFile );  
   }  
}  
Listing of .c files  

RDO HID SYS ARC  FILE         DATE                           SIZE  
--- --- --- ---  ----         ----                           ----  
 N   N   N   Y   blah.c       Wed Feb 13 09:21:42 2002       1715  
 N   N   N   Y   test.c       Wed Feb 06 14:30:44 2002        312  

请参阅See Also

系统调用System Calls