FindFirstFileA 함수(fileapi.h)

아티클
06/02/2023

디렉터리를 검색하여 특정 이름(와일드카드를 사용하는 경우 부분 이름)과 일치하는 이름을 가진 파일 또는 하위 디렉터리를 찾습니다.

검색에 사용할 추가 특성을 지정하려면 FindFirstFileEx 함수를 사용합니다.

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

구문

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

매개 변수

[in] lpFileName

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

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

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

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

팁

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

[out] lpFindFileData

찾은 파일 또는 디렉터리에 대한 정보를 수신하는 WIN32_FIND_DATA 구조체에 대한 포인터입니다.

반환 값

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

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

일치하는 파일을 찾을 수 없어 함수가 실패하면 GetLastError 함수는 ERROR_FILE_NOT_FOUND 반환합니다.

설명

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

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

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

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

검색 핸들이 설정되면 FindNextFile 함수를 사용하여 동일한 패턴과 일치하는 다른 파일을 검색하는 데 사용할 수 있습니다.

검색 핸들이 더 이상 필요하지 않으면 CloseHandle이 아닌 FindClose 함수를 사용하여 닫습니다.

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

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

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

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

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

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

디렉터리의 모든 파일을 나열하는 32비트 애플리케이션을 작성 중이고 애플리케이션이 64비트 컴퓨터에서 실행될 수 있는 경우 FindFirstFile을 호출하기 전에 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)	예

예제

다음 C++ 예제에서는 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 = 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);
   }
}

또 다른 예제는 디렉터리에 파일 나열을 참조하세요.

참고

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

요구 사항

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