RAD Studio
ContentsIndex
PreviousUpNext
findfirst, _wfindfirst

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:

FA_RDONLY 
Read-only attribute  
FA_HIDDEN 
Hidden file  
FA_SYSTEM 
System file  
FA_LABEL 
Volume label  
FA_DIREC 
Directory  
FA_ARCH  
Archive  

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:  

Bits 0 to 4 
The result of seconds divided by 2 (for example 10 here means 20 seconds)  
Bits 5 to 10 
Minutes  
Bits 11 to 15 
Hours  

ff_fdate:

Bits 0-4 
Day  
Bits 5-8 
Month  
Bits 9-15 
Years since 1980 (for example 9 here means 1989)  

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
 

 

ENOENT 
Path or file name not found  

  • _doserrno is set to one of the following values:
 

ENMFILE 
No more files  
ENOENT 
Path or file name not found  

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

 
POSIX 
Win32 
ANSI C 
ANSI C++ 
findfirst  
 
+  
 
 
_wfindfirst  
 
NT only  
 
 
Copyright(C) 2008 CodeGear(TM). All Rights Reserved.
What do you think about this topic? Send feedback!