디렉터리에서 특정 이름과 일치하는 이름으로 파일 또는 하위 디렉터리를 검색합니다(또는 와일드카드를 사용하는 경우 부분 이름).
검색에 사용할 추가 특성을 지정하려면 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
함수가 lpFileName 매개 변수의 검색 문자열에서 파일을 찾지 못하거나 실패하면 반환 값이 INVALID_HANDLE_VALUElpFindFileData 내용이 확정되지 않습니다. 확장 오류 정보를 얻으려면 GetLastError 함수를 호출합니다.
일치하는 파일을 찾을 수 없어 함수가 실패하면 GetLastError 함수는 ERROR_FILE_NOT_FOUND반환합니다.
발언
FindFirstFile 함수는 검색 핸들을 열고 지정된 패턴과 일치하는 이름으로 파일 시스템에서 찾은 첫 번째 파일에 대한 정보를 반환합니다. 동일한 파일 이름 문자열 패턴이 지정된 경우 디렉터리 목록 애플리케이션(예: dir 명령)에 표시되는 첫 번째 파일 또는 디렉터리일 수도 있습니다. FindFirstFile
다음 목록에서는 몇 가지 다른 검색 특성을 식별합니다.
- 검색은 날짜 또는 파일 형식과 같은 특성이 아니라 파일 이름에 따라 엄격하게 수행됩니다(다른 옵션의 경우 findFirstFileEx
참조). - 검색에는 길고 짧은 파일 이름이 포함됩니다.
- 후행 백슬래시를 사용하여 검색을 열려는 시도는 항상 실패합니다.
- lpFileName 매개 변수에 대해 잘못된 문자열, NULL또는 빈 문자열을 전달하는 것은 이 함수를 잘못 사용하는 것이 아닙니다. 이 경우 결과는 정의되지 않습니다.
참고 드문 경우나 로드된 시스템에서는 이 함수가 호출될 때 NTFS 파일 시스템에 대한 파일 특성 정보가 최신 정보가 아닐 수 있습니다. 현재 NTFS 파일 시스템 파일 특성을 가져오려면 GetFileInformationByHandle 함수를 호출합니다.
검색 핸들이 더 이상 필요하지 않으면 CloseHandle
앞에서 설명한 대로 lpFileName 입력 문자열에서 FindFirstFile후행 백슬래시(\)를 사용할 수 없으므로 루트 디렉터리를 검색하는 방법이 명확하지 않을 수 있습니다. 파일을 보거나 루트 디렉터리의 특성을 얻으려면 다음 옵션이 적용됩니다.
- 루트 디렉터리의 파일을 검사하려면 "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 호출하기 전에
경로가 기호 링크를 가리키는 경우 WIN32_FIND_DATA 버퍼에는 대상이 아닌 기호 링크에 대한 정보가 포함됩니다.
Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술에서 지원됩니다.
| 기술 | 지원 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | 예 |
| SMB 3.0 TFO(투명한 장애 조치(failover) | 예 |
| SO(스케일 아웃 파일 공유)가 있는 SMB 3.0 | 예 |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | 예 |
| ReFS(복원 파일 시스템) | 예 |
예제
다음 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 |
참고 항목
findClose
FindFirstFileEx
findFirstFileTransacted
FindNextFile
GetFileAttributes
setFileAttributes
windows 헤더 사용하는