Show: Delphi C++
Display Preferences

findfirst, _wfindfirst

From RAD Studio
Jump to: navigation, search

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

Personal tools
In other languages
Previous Versions
Assistance