FindFirstFileA 함수(fileapi.h)
디렉터리를 검색하여 특정 이름(와일드카드를 사용하는 경우 부분 이름)과 일치하는 이름을 가진 파일 또는 하위 디렉터리를 찾습니다.
검색에 사용할 추가 특성을 지정하려면 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 또는 빈 문자열을 전달하는 것은 이 함수를 잘못 사용하는 것이 아닙니다. 이 경우 결과는 정의되지 않습니다.
검색 핸들이 더 이상 필요하지 않으면 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 |