NtQueryInformationFile 함수(ntifs.h)

아티클
07/11/2023

NtQueryInformationFile 루틴은 파일 개체에 대한 다양한 종류의 정보를 반환합니다. 몇 가지 파일 정보 클래스에 보다 효율적으로 사용할 수 있는 NtQueryInformationByName도 참조하세요.

구문

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

매개 변수

[in] FileHandle

파일 개체에 대한 핸들입니다. 핸들은 NtCreateFile 또는 NtOpenFile에 대한 성공적인 호출 또는 동등한 파일 만들기 또는 열기 루틴에 의해 만들어집니다.

[out] IoStatusBlock

최종 완료 상태 받는 IO_STATUS_BLOCK 구조체 및 작업에 대한 정보를 가리키는 포인터입니다. 정보 멤버는 이 루틴이 실제로 FileInformation 버퍼에 쓰는 바이트 수를 받습니다.

[out] FileInformation

루틴이 파일 개체에 대해 요청된 정보를 쓰는 호출자가 할당한 버퍼에 대한 포인터입니다. FileInformationClass 매개 변수는 호출자가 요청하는 정보의 형식을 지정합니다.

[in] Length

FileInformation이 가리키는 버퍼의 크기(바이트)입니다.

[in] FileInformationClass

FileInformation이 가리키는 버퍼에서 파일에 대해 반환할 정보의 형식을 지정합니다. 디바이스 및 중간 드라이버는 다음 FILE_INFORMATION_CLASS 값(가장 낮은 값에서 가장 높은 열거형 값으로 나열됨)을 지정할 수 있습니다.

FILE_INFORMATION_CLASS 값	반환된 정보 유형
FileBasicInformation (4)	FILE_BASIC_INFORMATION 구조체입니다. 호출자가 DesiredAccess 매개 변수에 지정된 FILE_READ_ATTRIBUTES 플래그를 사용하여 파일을 열었어야 합니다.
FileStandardInformation (5)	FILE_STANDARD_INFORMATION 구조체입니다. 호출자는 DesiredAccess에 대한 특정 요구 사항 없이 파일이 열려 있는 한 이 정보를 쿼리할 수 있습니다.
FileInternalInformation (6)	FILE_INTERNAL_INFORMATION 구조체입니다. 이 구조체는 NTFS에서 파일을 고유하게 식별하는 64비트 파일 ID를 지정합니다. 다른 파일 시스템에서는 이 파일 ID가 고유하지 않습니다.
FileEaInformation (7)	FILE_EA_INFORMATION 구조체입니다. 이 구조체는 파일과 연결된 확장 특성 블록의 크기를 지정합니다.
FileAccessInformation (8)	FILE_ACCESS_INFORMATION 구조체입니다. 이 구조체에는 액세스 마스크가 포함되어 있습니다. 액세스 마스크에 대한 자세한 내용은 ACCESS_MASK 참조하세요.
FileNameInformation (9)	FILE_NAME_INFORMATION 구조체입니다. 구조체는 파일의 전체 경로 또는 일부만 포함할 수 있습니다. 호출자는 DesiredAccess에 대한 특정 요구 사항 없이 파일이 열려 있는 한 이 정보를 쿼리할 수 있습니다. 파일 이름 구문에 대한 자세한 내용은 이 항목의 뒷부분에 있는 설명 섹션을 참조하세요.
FilePositionInformation (14)	FILE_POSITION_INFORMATION 구조체입니다. 호출자는 DesiredAccess 매개 변수에 지정된 DesiredAccess FILE_READ_DATA 또는 FILE_WRITE_DATA 플래그와 CreateOptions 매개 변수에 지정된 FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT 플래그를 사용하여 파일을 열어야 합니다.
FileModeInformation (16)	FILE_MODE_INFORMATION 구조체입니다. 이 구조체에는 파일에 액세스할 수 있는 모드를 지정하는 플래그 집합이 포함되어 있습니다. 이러한 플래그는 IoCreateFile 루틴의 CreateOptions 매개 변수에 지정할 수 있는 옵션의 하위 집합입니다.
FileAlignmentInformation (17)	FILE_ALIGNMENT_INFORMATION 구조체입니다. 호출자는 DesiredAccess에 대한 특정 요구 사항 없이 파일이 열려 있는 한 이 정보를 쿼리할 수 있습니다. 이 정보는 CreateOptions 매개 변수에 지정된 FILE_NO_INTERMEDIATE_BUFFERING 플래그를 사용하여 파일을 연 경우에 유용합니다.
FileAllInformation (18)	FILE_ALL_INFORMATION 구조체입니다. 여러 파일 정보 구조를 단일 구조로 결합하여 FILE_ALL_INFORMATION 파일에 대한 정보를 가져오는 데 필요한 쿼리 수를 줄입니다.
FileAlternateNameInformation (21)	파일의 대체 이름 정보(8.3 형식 이름)를 반환하는 FILE_ALL_INFORMATION 구조체입니다.
FileStreamInformation (22)	파일 또는 디렉터리의 데이터 스트림을 열거할 FILE_STREAM_INFORMATION 구조체의 버퍼입니다.
FileCompressionInformation (28)	파일에 대한 압축 정보를 반환할 FILE_COMPRESSION_INFORMATION 구조체입니다.
FileNetworkOpenInformation (34)	FILE_NETWORK_OPEN_INFORMATION 구조체입니다. 호출자가 DesiredAccess 매개 변수에 지정된 FILE_READ_ATTRIBUTES 플래그를 사용하여 파일을 열었어야 합니다.
FileAttributeTagInformation (35)	FILE_ATTRIBUTE_TAG_INFORMATION 구조체입니다. 호출자가 DesiredAccess 매개 변수에 지정된 FILE_READ_ATTRIBUTES 플래그를 사용하여 파일을 열었어야 합니다.
FileIoPriorityHintInformation (43)	FILE_IO_PRIORITY_HINT_INFORMATION 구조체입니다. 호출자가 DesiredAccess 매개 변수에 지정된 FILE_READ_DATA 플래그로 파일을 열었어야 합니다.
FileSfioReserveInformation (44)	FILE_SFIO_RESERVE_INFORMATION 구조체입니다.
FileHardLinkInformation (46)	FILE_LINKS_INFORMATION 구조체입니다.
FileNormalizedNameInformation (48)	파일의 정규화된 이름을 반환할 FILE_NAME_INFORMATION 구조체입니다.
FileIsRemoteDeviceInformation (51)	FILE_IS_REMOTE_DEVICE_INFORMATION 구조체입니다. 호출자는 DesiredAccess에 대한 특정 요구 사항 없이 파일이 열려 있는 한 이 정보를 쿼리할 수 있습니다.
FileStandardLinkInformation (54)	FILE_STANDARD_LINK_INFORMATION 구조체입니다.
FileIdInformation (59)	FILE_ID_INFORMATION 구조체입니다.
FileDesiredStorageClassInformation (67)	FILE_DESIRED_STORAGE_CLASS_INFORMATION 구조체입니다.
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION 구조체입니다. 호출자가 DesiredAccess 매개 변수에 지정된 FILE_READ_ATTRIBUTES 플래그를 사용하여 파일을 열었어야 합니다. 이 값은 Windows 10 버전 1803부터 사용할 수 있습니다.
FileStorageReserveIdInformation (74)	FILE_STORAGE_RESERVE_ID_INFORMATION 구조체입니다.
FileCaseSensitiveInformationForceAccessCheck (75)	FILE_CASE_SENSITIVE_INFORMATION 구조체입니다. 호출자가 DesiredAccess 매개 변수에 지정된 FILE_READ_ATTRIBUTES 플래그를 사용하여 파일을 열었어야 합니다. 이는 사용자 모드 호출자에게 적용되는 검사와 유사하게 IOManager가 커널 모드 드라이버에 대한 액세스 검사를 수행하도록 강제하는 데 사용되는 FileCaseSensitiveInformation 작업의 특수 버전입니다. 이 작업은 IOManager에서만 인식되며 파일 시스템은 이를 수신해서는 안 됩니다. 이 값은 Windows 10 버전 1803부터 사용할 수 있습니다.
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION 구조체입니다. Windows Server 2022부터 사용할 수 있습니다.

반환 값

NtQueryInformationFile 은 STATUS_SUCCESS 또는 적절한 NTSTATUS 오류 코드를 반환합니다.

설명

NtQueryInformationFile 은 지정된 파일 개체에 대한 정보를 반환합니다. 특정 디바이스 또는 파일 시스템에서 지원하지 않는 FILE_XXX_INFORMATION 구조체의 모든 멤버에서 0을 반환합니다.

FileInformationClass = FileNameInformation이면 파일 이름이 FILE_NAME_INFORMATION 구조에 반환됩니다. 파일 이름의 정확한 구문은 다음과 같은 여러 요인에 따라 달라집니다.

NtCreateFile에 전체 경로를 제출하여 파일을 연 경우 NtQueryInformationFile은 해당 전체 경로를 반환합니다.
ObjectAttributes-RootDirectory> 핸들이 NtCreateFile 호출에서 이름으로 열렸고 이후에 이 루트 디렉터리 핸들을 기준으로 NtCreateFile에서 파일을 연 경우 NtQueryInformationFile은 전체 경로를 반환합니다.
NtCreateFile 호출에서 파일 ID(FILE_OPEN_BY_FILE_ID 플래그 사용)로 ObjectAttributes-RootDirectory> 핸들을 연 후 이 루트 디렉터리 핸들을 기준으로 NtCreateFile에서 파일을 연 경우 NtQueryInformationFile은 상대 경로를 반환합니다.
그러나 사용자에게 SeChangeNotifyPrivilege(Microsoft Windows SDK 설명서에 설명되어 있음)가 있는 경우 NtQueryInformationFile은 모든 경우에 전체 경로를 반환합니다.
상대 경로만 반환되는 경우 파일 이름 문자열은 백슬래시로 시작되지 않습니다.
전체 경로 및 파일 이름이 반환되면 문자열은 위치에 관계없이 단일 백슬래시로 시작합니다. 따라서 파일 C:\dir1\dir2\filename.ext는 \dir1\dir2\filename.ext로 표시되며 ,\server\share\dir1\dir2\filename.ext 파일은 \server\share\dir1\dir2\filename.ext로 표시됩니다.

버퍼 오버플로로 인해 NtQueryInformationFile이 실패하는 경우 FileNameInformation을 구현하는 드라이버는 버퍼에 맞는 만큼 파일 이름의 WCHAR 문자를 반환하고 FILE_NAME_INFORMATION 구조체의 FileNameLength 매개 변수에 필요한 전체 길이를 지정해야 합니다. 전체 파일 이름을 검색할 수 있도록 파일 이름 길이를 사용하여 쿼리를 다시 시작해야 합니다. 이 패턴을 따르지 않는 드라이버는 전체 파일 이름을 검색할 때까지 점진적으로 길이를 늘려야 할 수 있습니다. 파일 작업에 대한 자세한 내용은 드라이버에서 파일 사용을 참조하세요.

NtQueryInformationFile의 호출자는 IRQL = PASSIVE_LEVEL 및 특수 커널 APC를 사용하도록 설정된 상태에서 실행되어야 합니다.

참고

이 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwQueryInformationFile" 대신 "NtQueryInformationFile" 이름을 사용해야 합니다.

커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000.
대상 플랫폼	유니버설
헤더	ntifs.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL(설명 섹션 참조)
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs, PowerIrpDDis