findfirst

checked against scan

Searches a disk directory.

Defined in header <dir.h>

Syntax

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

Portability

DOS	UNIX	Windows	ANSI C	C++ only
■		■

Remarks

findfirst begins a search of a disk directory by using the DOS system call 0x4E.

pathname is a string with an optional drive specifier, path, and file name of the file to be found. 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.

The format of the structure ffblk is as follows:

struct ffblk {
   char ff_reserved[21];     /* reserved by DOS */
   char ff_attrib;           /* attribute found */
   int  ff_ftime;            /* file time */
   int  ff_fdate;            /* file date */
   long ff_fsize;            /* file size */
   char ff_name[13];         /* found file name */
};

attrib is a DOS file-attribute byte used in selecting eligible files for the search. attrib can be one of 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

For more detailed information about these attributes, refer to your DOS reference manuals.

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

ff_ftime:

bits 0 to 4	The result of seconds divided by 2 (e.g.	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 (e.g.	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. See getftime or setftime for examples.

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 some error in the file name, -1 is returned, and the global variable errno is set to

ENOENT	Path or file name not found

and doserno is set to one of the following:

ENOENT	Path or file name not found
ENMFILE	No more files

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

Program output

Directory listing of *.*
   FINDFRST.C
   FINDFRST.OBJ
   FINDFRST.EXE

Differences from modern implementations

Draft from general knowledge; not yet confirmed against the Borland run-time code.

There is no direct modern equivalent. Microsoft’s _findfirst takes (const char *filespec, struct _finddata_t *fileinfo), returns a search handle (−1 on failure) that you pass to _findnext and close with _findclose, and fills a different structure (attrib, time_create/time_access/time_write as time_t, size, name). Borland’s version keeps all search state in the caller’s ffblk (its 21 reserved bytes are the DOS search state), so nothing has to be closed.
POSIX has no attribute filter or DOS wildcard matching built in: use opendir/readdir with fnmatch, or glob.
Wildcards follow DOS rules (*.* matches every name, including ones without an extension). Names are 8.3 and uppercase, and ff_name holds at most 12 characters plus the NUL.
Attribute semantics come from DOS function 4Eh: with attrib = 0 only normal files are returned. Setting FA_HIDDEN, FA_SYSTEM or FA_DIREC adds those entries to the normal files rather than restricting the search to them.
The manual’s “doserno” means the global variable _doserrno.
Time stamps are packed DOS date/time words (see the bit layout above) with 2-second resolution, not time_t.

Modern references

Stable link: /3.1/dir.h/findfirst/ · short form /3.1/findfirst/