FindFirstFile

The FindFirstFile function searches a directory for a file whose name matches the specified filename. FindFirstFile examines subdirectory names as well as file names.

Parameters

lpszSearchFile

Points to a null-terminated string. This string must be a valid directory or path and filename, and may contain wildcard characters ('*' and '?').

lpffd

Points to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory if the function is successful.

The WIN32_FIND_DATA structure has the following format:

typedef struct _WIN32_FIND_DATA { /* wfd */

DWORD dwFileAttributes;

FILETIME ftCreationTime;

FILETIME ftLastAccessTime;

FILETIME ftLastWriteTime;

DWORD nFileSizeHigh;

DWORD nFileSizeLow;

DWORD dwReserved0;

DWORD dwReserved1;

CHAR cFileName[ MAX_PATH ];

CHAR cAlternateFileName[ 14 ];

} WIN32_FIND_DATA, *PWI32_FIND_DATA, *LPWIN32_FIND_DATA;

Return Value

If the function is successful, the return value is a search handle that can be used in a subsequent call to FindNextFile or FindClose.

If the function fails, the return value is INVALID_HANDLE_VALUE. Use the GetLastError function to obtain extended error information.

Comments

This function opens a search handle and returns information about the first file whose name matches the specified pattern. Once the search handle is established, the FindNextFile function can be used to search for other files that match the same pattern. When the search handle is no longer needed, it should be closed with the FindClose function.

This function searches for files by name only; it cannot be used for attribute-based searches.

The FindFirstFile function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

See Also

FindClose, FindNextFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA