findfirst, _wfindfirst

Go Up to dir.h Index

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

#include <stdio.h>
#include <dir.h>
void print_dir(wchar_t* dir_name)
{
  /* Open a find stream (_wfinddata_t and a find handle) */ 
  _wffblk find_data;
  int done;

  done = _wfindfirst(dir_name, &find_data, 0);

  /* Scan all files that mach */
  while (!done)
  {
    printf("%ls\n", find_data.ff_name);
    done = _wfindnext(&find_data);
  }

  /* Close the find handle */
  _wfindclose(&find_data);
}

Portability

	POSIX	Win32	ANSI C	ANSI C++
findfirst		+
_wfindfirst		NT only

See Also

• findclose, _wfindclose
• findnext, _wfindnext