Header File 

dir.h  

Category 

Directory Control Routines 

Prototype 

int findfirst(const char *pathname, struct ffblk *ffblk, int attrib); 

int _wfindfirst( const wchar_t *pathname, struct _wffblk *ffblk, int attrib); 

Description 

Searches a disk directory. 

findfirst begins a search of a disk directory for files specified by attributes or wildcards. 

pathname is a string with an optional drive specifier path and file name of the file to be found. Only the file name portion can contain wildcard match characters (such as ? or *). If a matching file is found the ffblk structure is filled with the file-directory information. 

When Unicode is defined, the _wfindfirst function uses the following _wffblk structure. 

struct _wffblk { 

long ff_reserved; 

long ff_fsize; 

unsigned long ff_attrib; 

unsigned short ff_ftime; 

unsigned short ff_fdate; 

wchar_t ff_name[256]; 

}; 

For Win32, the format of the structure ffblk is as follows: 

struct ffblk { 

long ff_reserved; 

long ff_fsize; /* file size */ 

unsigned long ff_attrib; /* attribute found */ 

unsigned short ff_ftime; /* file time */ 

unsigned short ff_fdate; /* file date */ 

char ff_name[256]; /* found file name */ 

}; 

attrib is a file-attribute byte used in selecting eligible files for the search. attrib should be selected from the following constants defined in dos.h:

A combination of constants can be OR’ed together. 

For more detailed information about these attributes refer to your operating system documentation. 

ff_ftime and ff_fdate contain bit fields for referring to the current date and time. The structure of these fields was established by the operating system. Both are 16-bit structures divided into three fields. 

ff_ftime:  

ff_fdate:

The structure ftime declared in io.h uses time and date bit fields similar in structure to ff_ftime and ff_fdate. 

Return Value 

findfirst returns 0 on successfully finding a file matching the search pathname. 

When no more files can be found, or if there is an error in the file name:

• -1 is returned
• errno is set to

• _doserrno is set to one of the following values:

Example

/* findfirst and findnext example */
#include <stdio.h>
#include <dir.h>
int main(void)
{
   struct ffblk ffblk;
   int done;
   printf("Directory listing of *.*\n");
   done = findfirst("*.*",&ffblk,0);
   while (!done) 
   {
      printf("  %s\n", ffblk.ff_name);
      done = findnext(&ffblk);
   }
   return 0;
}

Portability