Searches a directory for a file or subdirectory with a name that matches a specific name (or partialname if wildcards are used).

To specify additional attributes to use in a search, use theFindFirstFileEx function.

To perform this operation as a transacted operation, use theFindFirstFileTransacted function.

Syntax

HANDLE FindFirstFileA(  [in]  LPCSTR             lpFileName,  [out] LPWIN32_FIND_DATAA lpFindFileData);

Parameters

[in] lpFileName

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 beNULL, an invalid string (for example, an empty stringor 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 permissions tothe root and all subdirectories on the path.

By default, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, seeNaming Files, Paths, and Namespaces.

[out] lpFindFileData

A pointer to theWIN32_FIND_DATA structure thatreceives information about a found file or directory.

Return value

If the function succeeds, the return value is a search handle used in a subsequent call toFindNextFile orFindClose, and thelpFindFileData parameter contains information about the first file or directoryfound.

If the function fails or fails to locate files from the search string in thelpFileName parameter, the return value isINVALID_HANDLE_VALUE and the contents oflpFindFileData areindeterminate. To get extended error information, call theGetLastError function.

If the function fails because no matching files can be found, theGetLastError function returnsERROR_FILE_NOT_FOUND.

Remarks

TheFindFirstFile function opens a search handle andreturns information about the first file that the file system finds with a name that matches the specifiedpattern. This may or may not be the first file or directory that appears in a directory-listing application (suchas the dir command) when given the same file name string pattern. This is becauseFindFirstFile does no sorting of the search results. Foradditional information, seeFindNextFile.

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 (for other options, seeFindFirstFileEx).
• 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 thelpFileName parameter is not a valid use of this function. Results in this case are undefined.

When the search handle is no longer needed, close it by using theFindClose function, notCloseHandle.

As stated previously, you cannot use a trailing backslash (\) in thelpFileNameinput string forFindFirstFile, therefore it may not beobvious how to search root directories. If you want to see files or get the attributes of a root directory, thefollowing options would apply:

• To examine files in a root directory, you can use "C:\*" and step through the directory by usingFindNextFile.
• To get the attributes of a root directory, use theGetFileAttributes function.

On network shares, you can use anlpFileName in the form of the following:"\\Server\Share\*". However, you cannot use anlpFileNamethat points to the share itself; for example, "\\Server\Share" is not valid.

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

Be aware that some other thread or process could create or delete a file with this name between the time youquery 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 theCreateFile function withCREATE_NEW (which fails if the file exists) orOPEN_EXISTING(which fails if the file does not exist).

If you are writing a 32-bit application to list all the files in a directory and the application may be runon a 64-bit computer, you should call theWow64DisableWow64FsRedirection functionbefore callingFindFirstFile and callWow64RevertWow64FsRedirection after thelast call toFindNextFile. For more information, seeFile System Redirector.

If the path points to a symbolic link, theWIN32_FIND_DATA buffer contains information aboutthe symbolic link, not the target.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Examples

The following C++ example shows you a minimal use ofFindFirstFile.

#include <windows.h>#include <tchar.h>#include <stdio.h>void _tmain(int argc, TCHAR *argv[]){   WIN32_FIND_DATA FindFileData;   HANDLE hFind;   if( argc != 2 )   {      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);      return;   }   _tprintf (TEXT("Target file is %s\n"), argv[1]);   hFind = FindFirstFile(argv[1], &FindFileData);   if (hFind == INVALID_HANDLE_VALUE)    {      printf ("FindFirstFile failed (%d)\n", GetLastError());      return;   }    else    {      _tprintf (TEXT("The first file found is %s\n"),                 FindFileData.cFileName);      FindClose(hFind);   }}

For another example, seeListing the Files in a Directory.

Requirements

See also

File Management Functions

FindClose

FindFirstFileEx

FindFirstFileTransacted

FindNextFile

GetFileAttributes

SetFileAttributes

Symbolic Links

Using the Windows Headers

WIN32_FIND_DATA