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>

/* 32 bit file size and 32 bit time */
int findfirst(const char *filename, struct _find *find);
int findnext(struct _find *find);
int findclose(struct _find *find);

/* 64  bit file size and 32 bit time */
int _findfirst64(const char *filename, struct _find64 *find);
int _findnext64(struct _find64 *find);
int _findclose64(struct _find64 *find);

/* 64  bit file size and 64 bit time */
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.

findfirst(), findnext(), and findclose() are always 32 bit.

If you need to force the compiler to interpret time_t as the new 64-bit time_t, you can define _USE_64BIT_TIME_T. If _USE_64BIT_TIME_T is defined: _findfirst64(), _findnext64(), and _findclose64() are maped to _findfirst64x64(), _findnext64x64(), and _findclose64x64() and the struct _find64x64 is used with the calls. This is recommended to ensure that your application does not fail after January 18, 2038, but is not backwards-compatible with previous versions of INtime.

Return Values

0

Success.

-1

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

Requirements