FindFirstFileExA 함수(fileapi.h)

아티클
03/14/2023

디렉터리를 검색하여 지정된 이름 및 특성과 일치하는 파일 또는 하위 디렉터리를 찾습니다.

이 작업을 트랜잭션 작업으로 수행하려면 FindFirstFileTransacted 함수를 사용합니다.

구문

HANDLE FindFirstFileExA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

매개 변수

[in] lpFileName

디렉터리 또는 경로 및 파일 이름입니다. 파일 이름에는 와일드카드 문자(예: 별표(*) 또는 물음표(?)가 포함될 수 있습니다.

이 매개 변수는 NULL, 잘못된 문자열(예: 빈 문자열 또는 종료 null 문자가 누락된 문자열) 또는 후행 백슬래시(\)로 끝나서는 안 됩니다.

문자열이 와일드카드, 마침표 또는 디렉터리 이름으로 끝나는 경우 사용자는 경로의 루트 및 모든 하위 디렉터리에 액세스할 수 있어야 합니다.

기본적으로 이름은 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767자로 확장하려면 경로에 "\\?\"를 앞에 추가합니다. 자세한 내용은 파일 이름 지정, 경로 및 네임스페이스를 참조하세요.

팁

Windows 10 버전 1607부터 "\\?\"를 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을 참조하세요.

[in] fInfoLevelId

반환된 데이터의 정보 수준입니다.

이 매개 변수는 FINDEX_INFO_LEVELS 열거형 값 중 하나입니다.

[out] lpFindFileData

파일 데이터를 수신하는 버퍼에 대한 포인터입니다.

포인터 형식은 fInfoLevelId 매개 변수에 지정된 정보 수준에 따라 결정됩니다.

[in] fSearchOp

수행할 필터링 유형은 와일드카드 일치와 다릅니다.

이 매개 변수는 FINDEX_SEARCH_OPS 열거형 값 중 하나입니다.

lpSearchFilter

지정된 fSearchOp 에 구조적 검색 정보가 필요한 경우 검색 조건에 대한 포인터입니다.

현재 지원되는 fSearchOp 값에는 확장 검색 정보가 필요하지 않습니다. 따라서 이 포인터는 NULL이어야 합니다.

[in] dwAdditionalFlags

검색을 제어하는 추가 플래그를 지정합니다.

값	의미
FIND_FIRST_EX_CASE_SENSITIVE 1	검색은 대/소문자를 구분합니다.
FIND_FIRST_EX_LARGE_FETCH 2	찾기 작업의 성능을 높일 수 있는 디렉터리 쿼리에 더 큰 버퍼를 사용합니다. Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 값은 Windows Server 2008 R2 및 Windows 7까지 지원되지 않습니다.
FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY 4	결과를 디스크에 있는 파일로 제한합니다. 이 플래그는 파일 가상화 필터가 있는 경우에만 관련이 있습니다.

반환 값

함수가 성공하면 반환 값은 FindNextFile 또는 FindClose에 대한 후속 호출에 사용되는 검색 핸들이며 lpFindFileData 매개 변수에는 발견된 첫 번째 파일 또는 디렉터리에 대한 정보가 포함됩니다.

함수가 lpFileName 매개 변수의 검색 문자열에서 파일을 찾지 못하거나 실패하면 반환 값이 INVALID_HANDLE_VALUElpFindFileData 의 내용이 확정되지 않습니다. 확장 오류 정보를 가져오려면 GetLastError 함수를 호출합니다.

설명

FindFirstFileEx 함수는 검색 핸들을 열고 지정된 패턴과 일치하는 이름으로 파일 시스템에서 찾은 첫 번째 파일에 대한 정보를 반환합니다. 동일한 파일 이름 문자열 패턴이 지정된 경우 디렉터리 목록 애플리케이션(예: dir 명령)에 표시되는 첫 번째 파일 또는 디렉터리일 수도 있습니다. FindFirstFileEx가 검색 결과를 정렬하지 않기 때문입니다. 자세한 내용은 FindNextFile을 참조하세요.

다음 목록에서는 몇 가지 다른 검색 특성을 식별합니다.

검색은 날짜 또는 파일 형식과 같은 특성이 아니라 파일 이름에 따라 엄격하게 수행됩니다.
검색에는 길고 짧은 파일 이름이 포함됩니다.
후행 백슬래시를 사용하여 검색을 열려는 시도는 항상 실패합니다.
lpFileName 매개 변수에 대해 잘못된 문자열, NULL 또는 빈 문자열을 전달하는 것은 이 함수를 잘못 사용하는 것이 아닙니다. 이 경우 결과는 정의되지 않습니다.

참고 드문 경우나 로드가 많은 시스템에서는 이 함수가 호출될 때 NTFS 파일 시스템의 파일 특성 정보가 최신 정보가 아닐 수 있습니다. 현재 NTFS 파일 시스템 파일 특성을 가져오려면 GetFileInformationByHandle 함수를 호출합니다.

기본 파일 시스템에서 디렉터리 필터링 이외의 지정된 유형의 필터링을 지원하지 않으면 FindFirstFileEx 가 오류 ERROR_NOT_SUPPORTED 실패합니다. 애플리케이션은 FileExSearchNameMatchFINDEX_SEARCH_OPS 형식을 사용하고 자체 필터링을 수행해야 합니다.

검색 핸들이 설정되면 FindNextFile 함수에서 이 핸들을 사용하여 수행 중인 동일한 필터링과 동일한 패턴과 일치하는 다른 파일을 검색합니다. 검색 핸들이 필요하지 않은 경우 FindClose 함수를 사용하여 닫아야 합니다.

앞에서 설명한 것처럼 FindFirstFileEx에 대한 lpFileName 입력 문자열에서 후행 백슬래시(\)를 사용할 수 없으므로 루트 디렉터리를 검색하는 방법이 명확하지 않을 수 있습니다. 파일을 보거나 루트 디렉터리의 특성을 얻으려면 다음 옵션이 적용됩니다.

루트 디렉터리의 파일을 검사하려면 "C:\*"를 사용하고 FindNextFile을 사용하여 디렉터리를 단계별로 실행할 수 있습니다.
루트 디렉터리의 특성을 얻으려면 GetFileAttributes 함수를 사용합니다.

참고 문자열 "\\?\"을 앞에 추가해도 루트 디렉터리에 대한 액세스가 허용되지 않습니다.

네트워크 공유에서 lpFileName 을 다음 형식으로 사용할 수 있습니다. "\\server\service\*". 그러나 공유 자체를 가리키는 lpFileName 은 사용할 수 없습니다. 예를 들어 "\\server\service"가 잘못되었습니다.

루트 디렉터리가 아닌 디렉터리를 검사하려면 후행 백슬래시 없이 해당 디렉터리의 경로를 사용합니다. 예를 들어 "C:\Windows"의 인수는 "C:\Windows"의 디렉터리 또는 파일에 대한 정보가 아니라 디렉터리 "C:\Windows"에 대한 정보를 반환합니다. "C:\Windows"의 파일 및 디렉터리를 검사하려면 "C:\Windows\*"의 lpFileName 을 사용합니다.

다음 호출:

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

다음 호출과 동일합니다.

FindFirstFile( lpFileName, lpFindData );

다른 스레드 또는 프로세스는 결과를 쿼리하는 시간과 정보에 대해 작업하는 시간 사이에 이 이름의 파일을 만들거나 삭제할 수 있습니다. 이 문제가 애플리케이션에 대한 잠재적인 문제인 경우 한 가지 가능한 해결 방법은 createFile 함수를 CREATE_NEW (파일이 있는 경우 실패함) 또는 OPEN_EXISTING (파일이 없는 경우 실패)와 함께 사용하는 것입니다.

32비트 애플리케이션을 작성하여 디렉터리의 모든 파일을 나열하고 애플리케이션이 64비트 컴퓨터에서 실행될 수 있는 경우 FindFirstFileEx를 호출하기 전에 Wow64DisableWow64FsRedirection을 호출하고 FindNextFile에 대한 마지막 호출 후 Wow64RevertWow64FsRedirection을 호출해야 합니다. 자세한 내용은 파일 시스템 리디렉션기를 참조하세요.

경로가 바로 가기 링크를 가리키는 경우 WIN32_FIND_DATA 버퍼에는 대상이 아닌 바로 가기 링크에 대한 정보가 포함됩니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	예

예제

다음 코드는 FindFirstFileEx를 최소한으로 사용하는 방법을 보여줍니다. 이 프로그램은 FindFirstFile 항목의 예제와 동일합니다.

#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 = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
             FindExSearchNameMatch, NULL, 0);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFileEx failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

참고

fileapi.h 헤더는 FINDFirstFileEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll