NtSetInformationFile 함수(ntifs.h)

아티클
07/11/2023

NtSetInformationFile 루틴은 파일 개체에 대한 다양한 종류의 정보를 변경합니다.

구문

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

매개 변수

[in] FileHandle

파일 개체에 대한 핸들입니다. 이 핸들은 NtCreateFile 또는 NtOpenFile 을 성공적으로 호출하여 생성 됩니다.

[out] IoStatusBlock

최종 완료 상태 수신하는 IO_STATUS_BLOCK 구조체 및 요청된 작업에 대한 정보를 가리키는 포인터입니다. 정보 멤버는 파일에 설정된 바이트 수를 받습니다.

[in] FileInformation

파일에 대해 설정할 정보가 포함된 버퍼에 대한 포인터입니다. 이 버퍼의 특정 구조는 FileInformationClass 매개 변수에 의해 결정됩니다. 예를 들어 FileInformationClass 매개 변수가 FileDispositionInformationEx 상수로 설정된 경우 이 매개 변수는 FILE_DISPOSITION_INFORMATION_EX 구조체에 대한 포인터여야 합니다.

[in] Length

FileInformation 버퍼의 크기(바이트)입니다.

[in] FileInformationClass

파일에 대해 설정할 FileInformation이 가리키는 버퍼에 제공된 정보 형식입니다. 디바이스 및 중간 드라이버는 다음 FILE_INFORMATION_CLASS 값을 지정할 수 있습니다.

FILE_INFORMATION_CLASS 값	반환된 정보 유형
FileBasicInformation (4)	FILE_BASIC_INFORMATION 구조에 제공된 정보를 변경합니다. 호출자가 DesiredAccess 매개 변수에 설정된 FILE_WRITE_ATTRIBUTES 플래그로 파일을 열었어야 합니다.
FileRenameInformation (10)	FILE_RENAME_INFORMATION 구조에 제공된 현재 파일 이름을 변경합니다. 호출자는 파일에 대한 DELETE 액세스 권한이 있어야 합니다.
FileDispositionInformation (13)	파일을 닫을 때 삭제하거나 이전에 요청한 삭제를 취소하도록 요청합니다. 삭제 또는 취소 여부는 FILE_DISPOSITION_INFORMATION 구조에 제공됩니다. 호출자는 DesiredAccess 매개 변수에 DELETE 플래그가 설정된 파일을 열어야 합니다.
FilePositionInformation (14)	FILE_POSITION_INFORMATION 구조에 저장된 현재 파일 정보를 변경합니다.
FileEndOfFileInformation (20)	FILE_END_OF_FILE_INFORMATION 구조에 제공된 현재 파일 끝 정보를 변경합니다. 작업은 파일을 자르거나 확장할 수 있습니다. 호출자가 DesiredAccess 매개 변수에 설정된 FILE_WRITE_DATA 플래그로 파일을 열었어야 합니다.
FileValidDataLengthInformation (39)	FILE_VALID_DATA_LENGTH_INFORMATION 구조에 제공된 파일의 현재 유효한 데이터 길이를 변경합니다. 파일은 NTFS 볼륨에 있어야 하며 호출자는 DesiredAccess 매개 변수에 설정된 FILE_WRITE_DATA 플래그로 파일을 열어야 합니다. 관리자가 아닌 사용자 및 원격 사용자에게 는 SeManageVolumePrivilege 권한이 있어야 합니다.
FileShortNameInformation (40)	FILE_NAME_INFORMATION 구조에 제공된 현재 짧은 파일 이름을 변경합니다. 파일은 NTFS 볼륨에 있어야 하며 호출자는 DesiredAccess 매개 변수에 DesiredAccess DELETE 플래그가 설정된 파일을 열어야 합니다.
FileIoPriorityHintInformation (43)	파일 핸들에 대한 현재 기본 IRP 우선 순위 힌트를 변경합니다. 새 값은 FILE_IO_PRIORITY_HINT_INFORMATION 구조체에 제공됩니다. 이 구조체는 8 바이트 정렬되어야 합니다.
FileReplaceCompletionInformation (61)	지정된 파일 핸들에 대한 I/O 완료 포트를 변경하거나 제거합니다. 호출자는 포트 핸들 및 완료 키를 지정하는 FILE_COMPLETION_INFORMATION 구조체에 대한 포인터를 제공합니다. 포트 핸들이 NULL이 아닌 경우 이 핸들은 파일 핸들과 연결할 새 I/O 완료 포트를 지정합니다. 파일 핸들과 연결된 I/O 완료 포트를 제거하려면 구조체의 포트 핸들을 NULL로 설정합니다. 포트 핸들을 가져오기 위해 사용자 모드 호출자는 CreateIoCompletionPort 함수를 호출할 수 있습니다.
FileDispositionInformationEx (64)	파일을 삭제하거나 이전에 요청한 삭제를 취소하도록 요청합니다. 삭제 또는 취소 여부와 삭제 수행 시기 및 방법에 대한 설정이 FILE_DISPOSITION_INFORMATION_EX 구조에 제공됩니다. 호출자는 DesiredAccess 매개 변수에 DELETE 플래그가 설정된 파일을 열어야 합니다.
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION 구조에 제공된 정보를 변경합니다. 호출자가 DesiredAccess 매개 변수에 설정된 FILE_WRITE_ATTRIBUTES 플래그로 파일을 열었어야 합니다. 이 값은 Windows 10 버전 1803부터 사용할 수 있습니다.
FileLinkInformation (72)	FILE_LINK_INFORMATION 구조에 지정된 기존 파일에 대한 하드 링크를 만듭니다. 모든 파일 시스템에서 하드 링크를 지원하는 것은 아닙니다. 예를 들어 FAT는 그렇지 않은 동안에는 NTFS가 수행됩니다.
FileCaseSensitiveInformationForceAccessCheck (75)	FILE_CASE_SENSITIVE_INFORMATION 구조에 제공된 정보를 변경합니다. 호출자가 DesiredAccess 매개 변수에 설정된 FILE_WRITE_ATTRIBUTES 플래그로 파일을 열었어야 합니다. 이는 사용자 모드 호출자에게 적용되는 검사와 유사하게 IOManager가 커널 모드 드라이버에 대한 액세스 검사를 수행하도록 강제하는 데 사용되는 FileCaseSensitiveInformation 작업의 특수 버전입니다. 이 작업은 IOManager에서만 인식되며 파일 시스템은 이를 수신해서는 안 됩니다. 이 값은 Windows 10 버전 1803부터 사용할 수 있습니다.
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION 구조체입니다. Windows Server 2022부터 사용할 수 있습니다.

반환 값

NtSetInformationFile은 STATUS_SUCCESS 또는 적절한 오류 상태 반환합니다.

설명

NtSetInformationFile은 파일에 대한 정보를 변경합니다. 특정 디바이스 또는 파일 시스템에서 지원하지 않는 FILE_XXX_INFORMATION 구조체의 멤버를 무시합니다.

FileInformationClass를 FileDispositionInformation으로 설정하는 경우 이후에 FileHandle을 NtClose에 전달할 수 있지만 다른 ZwXxx파일 루틴에는 전달할 수 없습니다. FileDispositionInformation으로 인해 파일이 삭제되도록 표시되므로 파일을 닫는 것 이외의 핸들에 대한 후속 작업을 시도하는 것은 프로그래밍 오류입니다.

FileInformationClass를 FilePositionInformation으로 설정하고 NtCreateFile에 대한 이전 호출에 CreateOptions 매개 변수에 FILE_NO_INTERMEDIATE_BUFFERING 플래그가 포함된 경우 FILE_POSITION_INFORMATION 구조체의 CurrentByteOffset 멤버에 대한 특정 제한이 적용됩니다. 자세한 내용은 NtCreateFile을 참조하세요.

FileInformationClass를 FileEndOfFileInformation으로 설정하고 FILE_END_OF_FILE_INFORMATIONEndOfFile 멤버가 현재 파일 끝 표시를 초과하는 오프셋을 지정하는 경우 NtSetInformationFile은 파일을 확장하고 확장을 0으로 채운다.

파일 작업에 대한 자세한 내용은 드라이버에서 파일 사용을 참조하세요.

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

참고

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

커널 모드 드라이버에서 호출하는 경우 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