FindFirstFile
The FindFirstFile
function searches a directory for a file whose name matches the specified
filename. FindFirstFile examines subdirectory names as well as
filenames.
HANDLE FindFirstFile(
LPCTSTR lpFileName, |
// pointer to name
of file to search for |
LPWIN32_FIND_DATA lpFindFileData |
// pointer to
returned information |
); |
|
Parameters
lpFileName
Windows
95: Points to a null-terminated
string that specifies a valid directory or path and filename, which can contain
wildcard characters (* and ?). This string must not exceed MAX_PATH characters.
Windows
NT: Points to a null-terminated
string that specifies a valid directory or path and filename, which can contain
wildcard characters (* and ?).
There is a
default string size limit for paths of MAX_PATH characters. This limit is
related to how the FindFirstFile function parses paths. An application
can transcend this limit and send in paths longer than MAX_PATH characters by
calling the wide (W) version of FindFirstFile and prepending \\?\ to the path.
The \\?\ tells the function to turn off path parsing; it lets paths longer
than MAX_PATH be used with FindFirstFileW. This also works with UNC
names. The \\?\ is ignored as part of the path. For example, \\?\C:\myworld\private is seen as C:\myworld\private , and \\?\UNC\bill_g_1\hotstuff\coolapps is seen as \\bill_g_1\hotstuff\coolapps .
lpFindFileData
Points to the
WIN32_FIND_DATA
Return Values
If the
function succeeds, the return value is a search handle used in a subsequent
call to FindNextFile
If the
function fails, the return value is INVALID_HANDLE_VALUE. To get extended error
information, call GetLastError
Remarks
The FindFirstFile
function opens a search handle and returns information about the first file
whose name matches the specified pattern. Once the search handle is
established, you can use the FindNextFile function to search for other
files that match the same pattern. When the search handle is no longer needed,
close it by using the FindClose function.
This function
searches for files by name only; it cannot be used for attribute-based
searches.
See Also