FindFirstFile Function

Searches a directory for a file or subdirectory with a name that matches a specific name.

查找一个目录下的文件或子目录与一个已知的名字相匹配。

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

To perform this operation as a transacted operation, use the FindFirstFileTransacted function.

Syntax

HANDLE WINAPI FindFirstFile(  __in   LPCTSTR lpFileName,  __out  LPWIN32_FIND_DATA lpFindFileData);

Parameters

lpFileName

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

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 32,767 widecharacters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.

lpFindFileData

A pointer to the WIN32_FIND_DATA structure that receives information about a found file or subdirectory.

Return Value

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

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, callGetLastError.

Example Code1

#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);   }}

 

Example Code2

#include <windows.h>#include <tchar.h> #include <stdio.h>#include <strsafe.h>void ErrorHandler(LPTSTR lpszFunction);int _tmain(int argc, TCHAR *argv[]){   WIN32_FIND_DATA ffd;   LARGE_INTEGER filesize;   TCHAR szDir[MAX_PATH];   size_t length_of_arg;   HANDLE hFind = INVALID_HANDLE_VALUE;   DWORD dwError=0;      // If the directory is not specified as a command-line argument,   // print usage.   if(argc != 2)   {      _tprintf(TEXT("\nUsage: %s <directory name>\n"), argv[0]);      return (-1);   }   // Check that the input path plus 2 is not longer than MAX_PATH.   StringCchLength(argv[1], MAX_PATH, &length_of_arg);   if (length_of_arg > (MAX_PATH - 2))   {      _tprintf(TEXT("\nDirectory path is too long.\n"));      return (-1);   }   _tprintf(TEXT("\nTarget directory is %s\n\n"), argv[1]);   // Prepare string for use with FindFile functions.  First, copy the   // string to a buffer, then append '\*' to the directory name.   StringCchCopy(szDir, MAX_PATH, argv[1]);   StringCchCat(szDir, MAX_PATH, TEXT("\\*"));   // Find the first file in the directory.   hFind = FindFirstFile(szDir, &ffd);   if (INVALID_HANDLE_VALUE == hFind)    {      ErrorHandler(TEXT("FindFirstFile"));      return dwError;   }       // List all the files in the directory with some info about them.   do   {      if (ffd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY)      {         _tprintf(TEXT("  %s   <DIR>\n"), ffd.cFileName);      }      else      {         filesize.LowPart = ffd.nFileSizeLow;         filesize.HighPart = ffd.nFileSizeHigh;         _tprintf(TEXT("  %s   %ld bytes\n"), ffd.cFileName, filesize.QuadPart);      }   }   while (FindNextFile(hFind, &ffd) != 0);    dwError = GetLastError();   if (dwError != ERROR_NO_MORE_FILES)    {      ErrorHandler(TEXT("FindFirstFile"));   }   FindClose(hFind);   return dwError;}void ErrorHandler(LPTSTR lpszFunction) {     // Retrieve the system error message for the last-error code    LPVOID lpMsgBuf;    LPVOID lpDisplayBuf;    DWORD dw = GetLastError();     FormatMessage(        FORMAT_MESSAGE_ALLOCATE_BUFFER |         FORMAT_MESSAGE_FROM_SYSTEM |        FORMAT_MESSAGE_IGNORE_INSERTS,        NULL,        dw,        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),        (LPTSTR) &lpMsgBuf,        0, NULL );    // Display the error message and exit the process    lpDisplayBuf = (LPVOID)LocalAlloc(LMEM_ZEROINIT,         (lstrlen((LPCTSTR)lpMsgBuf)+lstrlen((LPCTSTR)lpszFunction)+40)*sizeof(TCHAR));     StringCchPrintf((LPTSTR)lpDisplayBuf,         LocalSize(lpDisplayBuf) / sizeof(TCHAR),        TEXT("%s failed with error %d: %s"),         lpszFunction, dw, lpMsgBuf);     MessageBox(NULL, (LPCTSTR)lpDisplayBuf, TEXT("Error"), MB_OK);     LocalFree(lpMsgBuf);    LocalFree(lpDisplayBuf);}