GetFirstFile

int GetFirstFile (char searchPath[], int normal, int readOnly, int system, int hidden, int archive, int directory, char fileName[]);

Purpose

Conducts a search for files with specified attributes and returns the first matching file.

If you select multiple attributes, a match occurs on the first file for which one or more of the specified attributes are set and that matches the pattern in searchPath. The search attributes are normal, readOnly, system, hidden, archive, and directory.

GetFirstFile honors all the attributes.

Linux GetFirstFile honors only the directory attribute. If you pass 1 for the directory attribute, only directories match. If you pass 0 for the directory attribute, only non-directories match.

The normal attribute specifies files with no attributes set or with only the archive bit set. If you specify only the normal attribute, GetFirstFile can return any file that is not read-only, not a system file, not hidden, and not a directory. Normal files can have the archive attribute on or off.

The readOnly attribute specifies files that are protected from modification or overwriting. If you specify the readOnly attribute, GetFirstFile can return any file that is read-only unless the file is a system (or hidden) file and you did not specify the system (or hidden) attribute.

The system and hidden attributes specify files that normally do not appear in a directory listing.

If you specify the system attribute, GetFirstFile can return any system file unless the file is also a hidden file and you did not specify the hidden attribute. If you do not specify the system attribute, a system file cannot match regardless of its other attributes.

If you specify the hidden attribute, GetFirstFile can return any hidden file unless the file is also a system file and you did not specify the system attribute. If you do not specify the hidden attribute, a hidden file cannot match regardless of its other attributes.

The archive attribute specifies files that have been modified because they were last backed up using the DOS backup command. The directory attribute specifies directories.

If you use more than one attribute, the effect is additive. GetFirstFile returns any file that meets only one of the attributes you specify regardless of the additional attributes you specify.

Call GetNextFile to get the names of other matching files. On Windows, the order in which these functions return the file names is dependent on the file system type. With the NTFS and CDFS file systems, the names are returned in alphabetical order. With FAT file systems, the names are returned in the order the files were written to the disk, which may or may not be in alphabetical order.

Parameters

Input
Name Type Description
searchPath string Path to search.

searchPath can contain the wildcard characters '*' and '?'.
normal integer Normal attribute. The normal attribute specifies files with no attributes set or with only the archive bit set.

Values
0—do not search for files with the attribute
1—search for files with the attribute
readOnly integer Read-only attribute.

The readOnly attribute specifies files that are protected from modification or overwriting.

Values
0—do not search for files with the attribute
1—search for files with the attribute
system integer System attribute.

The system attribute specifies files that normally do not appear in a directory listing.

Values
0—do not search for files with the attribute
1—search for files with the attribute
hidden integer Hidden attribute.

The hidden attribute specifies files that normally do not appear in a directory listing.

Values
0—do not search for files with the attribute
1—search for files with the attribute
archive integer Archive attribute.

The archive attribute specifies files that have been modified because they were last backed up using the DOS backup command.

Values
0—do not search for files with the attribute
1—search for files with the attribute
directory integer Directory attribute.

The directory attribute specifies directories.

Values
0—do not search for files with the attribute
1—search for files with the attribute
Output
Name Type Description
fileName string First file found.

fileName contains the basename and extension of the first matching file and must be at least MAX_FILENAME_LEN characters in length.

Return Value

Name Type Description
result integer Result of search.

Code Description
0 Success.
-1 No files found that match criteria.
-3 General I/O error occurred.
-4 Insufficient memory to complete the operation.
-5 Invalid path, for example, c:filename.
-6 Access denied.