findfirst, _wfindfirst
Remonter à 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 |