findfirst

Syntax

#include <dir.h> int findfirst(const char *pathname, struct ffblk *ffblk, int attrib);

Description

This function and the related findnext (see section findnext) are used to scan directories for the list of files therein. The pathname is a wildcard that specifies the directory and files to search for (such as subdir/*.c), ffblk is a structure to hold the results and state of the search, and attrib is a combination of the following:

FA_RDONLY

Include read-only files in the search (Ignored.)

FA_HIDDEN

Include hidden files in the search

FA_SYSTEM

Include system files in the search

FA_LABEL

Include the volume label in the search

FA_DIREC

Include subdirectories in the search

FA_ARCH

Include modified files in the search (Ignored.)

If a file has flag bits that are not specified in the attrib parameter, the file will be excluded from the results. Thus, if you specified FA_DIREC and FA_LABEL, subdirectories and the volume label will be included in the results. Hidden and system files will be excluded.

Since findfirst calls DOS function 4eh, it is not possible to exclude read-only files or archive files from the results. Even if the FA_ARCH and FA_RDONLY bits are not specified in the attrib parameter, the results will include any read-only and archive files in the directory searched.

This function supports long file names.

The results of the search are stored in ffblk, which is extended when the LFN API (see section LFN) is supported. Fields marked LFN are only valid if the lfn_magic member is set to "LFN32".

struct ffblk { char lfn_magic[6]; /* LFN: the magic "LFN32" signature */ short lfn_handle; /* LFN: the handle used by findfirst/findnext */ unsigned short lfn_ctime; /* LFN: file creation time */ unsigned short lfn_cdate; /* LFN: file creation date */ unsigned short lfn_atime; /* LFN: file last access time (usually 0) */ unsigned short lfn_adate; /* LFN: file last access date */ char ff_reserved[5]; /* used to hold the state of the search */ unsigned char ff_attrib; /* actual attributes of the file found */ unsigned short ff_ftime; /* hours:5, minutes:6, (seconds/2):5 */ unsigned short ff_fdate; /* (year-1980):7, month:4, day:5 */ unsigned long ff_fsize; /* size of file */ char ff_name[260]; /* name of file as ASCIIZ string */ }

Return Value

Zero if a match is found, nonzero if none found.

Portability

ANSI/ISO C	No
POSIX	No

Example

struct ffblk f; int done = findfirst("*.exe", &f, FA_HIDDEN | FA_SYSTEM); while (!done) { printf("%10u %2u:%02u:%02u %2u/%02u/%4u %s\n", f.ff_fsize, (f.ff_ftime >> 11) & 0x1f, (f.ff_ftime >> 5) & 0x3f, (f.ff_ftime & 0x1f) * 2, (f.ff_fdate >> 5) & 0x0f, (f.ff_fdate & 0x1f), ((f.ff_fdate >> 9) & 0x7f) + 1980, f.ff_name); done = findnext(&f); }