_find, _wfind Functions
These functions search for and close searches for specified filenames.
Remarks
The _findfirst function provides information about the first instance of a filename that matches the file specified in the filespec argument. Any wildcard combination supported by the host operating system can be used in filespec. File information is returned in a _finddata_t structure, defined in IO.H. The _finddata_t structure includes the following elements:
unsigned attrib
File attribute
time_t time_create
Time of file creation ( –1L for FAT file systems)
time_t time_access
Time of last file access (–1L for FAT file systems)
time_t time_write
Time of last write to file
_fsize_t size
Length of file in bytes
char name[_MAX_FNAME]
Null-terminated name of matched file/directory, without the path
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_FNAME is defined in STDLIB.H as 256 bytes.
You cannot specify target attributes (such as _A_RDONLY) by which to limit the find operation. This attribute is returned in the attrib field of the _finddata_t structure and can have the following values (defined in IO.H).
_A_ARCH
Archive. Set whenever the file is changed, and cleared by the BACKUP command. Value: 0x20
_A_HIDDEN
Hidden file. Not normally seen with the DIR command, unless the /AH option is used. Returns information about normal files as well as files with this attribute. Value: 0x02
_A_NORMAL
Normal. File can be read or written to without restriction. Value: 0x00
_A_RDONLY
Read-only. File cannot be opened for writing, and a file with the same name cannot be created. Value: 0x01
_A_SUBDIR
Subdirectory. Value: 0x10
_A_SYSTEM
System file. Not normally seen with the DIR command, unless the /A or /A:S option is used. Value: 0x04
_findnext finds the next name, if any, that matches the filespec argument specified in a prior call to _findfirst. The fileinfo argument should point to a structure initialized by a previous call to _findfirst. If a match is found, the fileinfo structure contents are altered as described above. _findclose closes the specified search handle and releases all associated resources for both _findfirst and _findnext. 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.
The _find functions allow nested calls. For example, if the file found by a call to _findfirst or _findnext is a subdirectory, a new search can be initiated with another call to _findfirst or _findnext.
_wfindfirst and _wfindnext are wide-character versions of _findfirst and _findnext. The structure argument of the wide-character versions has the _wfinddata_t data type, which is defined in IO.H and in WCHAR.H. 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 rather than type char. Otherwise _wfindfirst and _wfindnext behave identically to _findfirst and _findnext. Functions _findfirsti64, _findnexti64, _wfindfirsti64, and _wfindnexti64 also behave identically except they use and return 64-bit file lengths.
Example
/* FFIND.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 <io.h>
#include <time.h>
void main( void )
{
struct _finddata_t c_file;
long 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( "\nRDO HID SYS ARC FILE DATE %25c SIZE\n", ' ' );
printf( "--- --- --- --- ---- ---- %25c ----\n", ' ' );
printf( ( c_file.attrib & _A_RDONLY ) ? " Y " : " N " );
printf( ( c_file.attrib & _A_SYSTEM ) ? " Y " : " N " );
printf( ( c_file.attrib & _A_HIDDEN ) ? " Y " : " N " );
printf( ( c_file.attrib & _A_ARCH ) ? " Y " : " N " );
printf( " %-12s %.24s %9ld\n",
c_file.name, ctime( &( c_file.time_write ) ), c_file.size );
/* Find the rest of the .c files */
while( _findnext( hFile, &c_file ) == 0 )
{
printf( ( c_file.attrib & _A_RDONLY ) ? " Y " : " N " );
printf( ( c_file.attrib & _A_SYSTEM ) ? " Y " : " N " );
printf( ( c_file.attrib & _A_HIDDEN ) ? " Y " : " N " );
printf( ( c_file.attrib & _A_ARCH ) ? " Y " : " N " );
printf( " %-12s %.24s %9ld\n",
c_file.name, ctime( &( c_file.time_write ) ), c_file.size );
}
_findclose( hFile );
}
}
Output
Listing of .c files
RDO HID SYS ARC FILE DATE SIZE
--- --- --- --- ---- ---- ----
N N N Y CWAIT.C Tue Jun 01 04:07:26 1993 1611
N N N Y SPRINTF.C Thu May 27 04:59:18 1993 617
N N N Y CABS.C Thu May 27 04:58:46 1993 359
N N N Y BEGTHRD.C Tue Jun 01 04:00:48 1993 3726