RAD Studio |  |

findfirst, _wfindfirst
See Also
Collapse All

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

Copy Code

    /* 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 |  |

See Also

findclose

findnext

Copyright(C) 2009 Embarcadero Technologies, Inc. All Rights Reserved.
What do you think about this topic? Send feedback!