FindFirstFile

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

To specify additional attributes to be used in the search, use the FindFirstFileEx function.

HANDLE FindFirstFile(
  LPCTSTR lpFileName,               // file name
  LPWIN32_FIND_DATA lpFindFileData  // data buffer
);

Parameters

lpFileName

[in] Pointer to a null-terminated string that specifies a valid directory or path and file name, which can contain wildcard characters (* and ?).

Windows NT/2000: In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to nearly 32,000 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see File Name Conventions.

Windows 95/98: This string must not exceed MAX_PATH characters.

lpFindFileData

[out] Pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory.

Return Values

If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose.

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. After the search handle has been established, 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.

You cannot use root directories as the lpFileName input string for FindFirstFile, with or without a trailing backslash. To examine files in a root directory, use something like "C:\*" and step through the directory with FindNextFile. To get the attributes of a root directory, use GetFileAttributes. Prepending the string "\\?\" does not allow access to the root directory.

Similarly, on network shares, you can use an lpFileName of the form "\\server\service\*" but you cannot use an lpFileName that points to the share itself, such as "\\server\service".

To examine any directory other than a root directory, use an appropriate path to that directory, with no trailing backslash. For example, an argument of "C:\windows" will return information about the directory "C:\windows", not about any directory or file in "C:\windows". An attempt to open a search with a trailing backslash will always fail.

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

The following code shows a minimal use of FindFirstFile.

#define _WIN32_WINNT 0x0400

#include "windows.h"

int
main(int argc, char *argv[])
{
  WIN32_FIND_DATA FindFileData;
  HANDLE hFind;

  printf ("Target file is %s.\n", argv[1]);

  hFind = FindFirstFile(argv[1], &FindFileData);

  if (hFind == INVALID_HANDLE_VALUE) {
    printf ("Invalid File Handle. Get Last Error reports %d\n", GetLastError ());
  } else {
    printf ("The first file found is %s\n", FindFileData.cFileName);
    FindClose(hFind);
  }

  return (0);
}

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

File I/O Overview, File I/O Functions, FindClose, FindFirstFileEx, FindNextFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA