These functions are used to scan directories for the list of files in it. The filename parameter can contain a full or partial pathname and a filename. The filename part can contain wildcards * or ?, for example "subdir/*.c".

findfirst finds the first file which matches the specified pattern.

findnext finds the next file after an initial call to findfirst.

findclose closes the find handle and releases internal resources used to maintain context.

#include <sys/types.h>
#include <dirent.h>

int findfirst(const char *filename, struct _find *find);
int findnext(struct _find *find);
int findclose(struct _find *find);

int _findfirst64(const char *filename, struct _find64 *find);
int _findnext64(struct _find64 *find);
int _findclose64(struct _find64 *find);

int _findfirst64x64(const char *filename, struct _find64x64 *find);
int _findnext64x64(struct _find64x64 *find);
int _findclose64x64(struct _find64x64 *find);

Parameters

filename

Target filename. May use wildcards * and ?.

find

Pointer to structure of type struct _find or struct _find64. The pointer must refer to a valid memory buffer before the call.

Remarks

Information is returned in the struct _find or struct _find64 structure, which has the following format:

struct _find {
    DIR *f_dir;             // Pointer to internal state buffer
    char f_wildcard[16];    // Original filename specification
    char f_filename[16];    // Last matched filename
    unsigned f_size;        // Low 32 bits of file size
    unsigned f_size_hi;     // High 32 bits of file size
    mode_t f_mode;          // File mode, as described in chmod
    time_t f_atime;         // File access time, as returned by stat
    time_t f_mtime;         // File modification time
    time_t f_ctime;         // File creation time
};

struct _find64 {
    DIR *f_dir;                     // pointer to DIR context
    char f_wildcard[MAXNAMLEN+1];   // wildcard specification
    char f_filename[MAXNAMLEN+1];   // long filename
    char f_filename_alt[16];        // short filename
    unsigned long64 f_size;
    mode_t f_mode;          // File mode
    __time32_t f_atime;     // Time last accessed
    __time32_t f_mtime;     // Time last modified
    __time32_t f_ctime;     // Time created
};
        
struct _find64x64 {
    DIR *f_dir;                      // pointer to DIR context
    char f_wildcard[MAXNAMLEN+1];    // wildcard specification
    char f_filename[MAXNAMLEN+1];    // filename
    char f_filename_alt[16];         // short filename
    unsigned long64 f_size;
    mode_t f_mode;           // File mode
    __time64_t f_atime;      // Time last accessed
    __time64_t f_mtime;      // Time last modified
    __time64_t f_ctime;      // Time created
};

If findfirst or findnext fail (because there are no more names to match) then an implicit call to findclose is made. Call findclose to close a find context explicitly.

Return Values

0

Success.

-1

Failure. The value of errno will contain a valid status code.

Requirements