_find, _wfind Functions
div
TOC
Collapse the table of content
Expand the table of content
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

_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 (or _finddata64_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_PATH]
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_PATH is defined in STDLIB.H as 260 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). Users should not rely on these being the only values possible for the attrib field.

_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 has no other attributes set, and 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

// 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 <io.h>
#include <time.h>

int 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 );
   }
}

Sample Output

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 Routines | Run-Time Routines and .NET Framework Equivalents

Show:
© 2016 Microsoft