Parameters

The directory or path, and the file name. The file name can include wildcard characters, for example, an asterisk
(*) or a question mark (?).

This parameter should not be NULL, an invalid string (for example, an empty string
or a string that is missing the terminating null character), or end in a trailing backslash (\).

If the string ends with a wildcard, period, or directory name, the user must have access to the root and all
subdirectories on the path.

In the ANSI version of this function, the name is limited to MAX_PATH characters.
To extend this limit to approximately 32,000 wide characters, call the Unicode version of the function (FindFirstFileExW), and
prepend "\\?\" to the path. For more information, see
Naming a File.

Tip Starting in Windows 10, version 1607, for the unicode version of this function (FindFirstFileExW), you can opt-in to remove the MAX_PATH character limitation without prepending "\\?\". See the "Maximum Path Limitation" section of Naming Files, Paths, and Namespaces for details.

Return value

If the function succeeds, the return value is a search handle used in a subsequent call to
FindNextFile or
FindClose, and the
lpFindFileData parameter contains information about the first file or directory
found.

If the function fails or fails to locate files from the search string in the
lpFileName parameter, the return value is
INVALID_HANDLE_VALUE and the contents of lpFindFileData are
indeterminate. To get extended error information, call the
GetLastError function.

Remarks

The FindFirstFileEx function opens a search handle
and returns information about the first file that the file system finds with a name that matches the specified
pattern. This may or may not be the first file or directory that appears in a directory-listing application (such
as the dir command) when given the same file name string pattern. This is because
FindFirstFileEx does no sorting of the search results.
For additional information, see FindNextFile.

The following list identifies some other search characteristics:

The search is performed strictly on the name of the file, not on any attributes such as a date or a file
type.

The search includes the long and short file names.

An attempt to open a search with a trailing backslash always fails.

Passing an invalid string, NULL, or empty string for the
lpFileName parameter is not a valid use of this function. Results in this case are
undefined.

Note In rare cases or on a heavily loaded system, file attribute information on NTFS file systems may not be
current at the time this function is called. To be assured of getting the current NTFS file system file
attributes, call the
GetFileInformationByHandle function.

If the underlying file system does not support the specified type of filtering, other than directory
filtering, FindFirstFileEx fails with the error
ERROR_NOT_SUPPORTED. The application must use
FINDEX_SEARCH_OPS type
FileExSearchNameMatch and perform its own filtering.

After the search handle is established, use it in the
FindNextFile function to search for other
files that match the same pattern with the same filtering that is being performed. When the search handle is not
needed, it should be closed by using the
FindClose function.

As stated previously, you cannot use a trailing backslash (\) in the lpFileName
input string for FindFirstFileEx, therefore it may not
be obvious how to search root directories. If you want to see files or get the attributes of a root directory, the
following options would apply:

To examine files in a root directory, you can use "C:\*" and step through the directory by
using FindNextFile.

Note Prepending the string "\\?\" does not allow access to the root directory.

On network shares, you can use an lpFileName in the form of the following:
"\\server\service\*". However, you cannot use an lpFileName that points
to the share itself; for example, "\\server\service" is not valid.

To examine a directory that is not a root directory, use the path to that directory, without a trailing
backslash. For example, an argument of "C:\Windows" returns information about the
directory "C:\Windows", not about a directory or file in
"C:\Windows". To examine the files and directories in
"C:\Windows", use an lpFileName of
"C:\Windows\*".

Be aware that some other thread or process could create or delete a file with this name between the time you
query for the result and the time you act on the information. If this is a potential concern for your application,
one possible solution is to use the CreateFile function with
CREATE_NEW (which fails if the file exists) or OPEN_EXISTING
(which fails if the file does not exist).