共用方式為


NtSetInformationFile 函式 (ntifs.h)

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

檔案物件的句柄。 此句柄是由 成功呼叫 NtCreateFileNtOpenFile 所建立。

[out] IoStatusBlock

接收最終完成狀態和所要求作業相關信息 之IO_STATUS_BLOCK 結構的指標。 Information 成員會接收檔案上設定的位元組數目。

[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 結構中指定的。 並非所有文件系統都支援硬式連結;例如,NTFS 會執行 ,但 FAT 則不會。
FileCaseSensitiveInformationForceAccessCheck (75) 變更 FILE_CASE_SENSITIVE_INFORMATION 結構中提供的資訊。 呼叫端必須已開啟檔案,並在 DesiredAccess 參數中設定FILE_WRITE_ATTRIBUTES旗標。 這是 FileCaseSensitiveInformation 作業的特殊版本,可用來強制 IOManager 執行核心模式驅動程式的存取檢查,類似於套用至使用者模式呼叫端的檢查。 這項作業只能由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 會擴充檔案,並將擴展名填補為零。

如需使用檔案的詳細資訊,請參閱 在驅動程式中使用檔案

NtSetInformationFile 的呼叫端必須在 IRQL = PASSIVE_LEVEL且啟用特殊核心 APC 時執行

注意

如果在使用者模式中呼叫此函式,請使用名稱 「NtSetInformationFile」,而不是 「ZwSetInformationFile」。。

針對來自內核模式驅動程式的呼叫,Windows 原生系統服務例程的 NtXxxZwXxx 版本會以處理和解譯輸入參數的方式,以不同的方式運作。 如需 NtXxx*** 和 ZwXxx*** 例程版本之間關聯性的詳細資訊,請參閱 使用 Nt 和 Zw 版本的原生系統服務例程

規格需求

需求
最低支援的用戶端 Windows 2000。
目標平台 Universal
標頭 ntifs.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則 HwStorPortProhibitedDIS、 PowerIrpDDis

另請參閱

CreateIoCompletionPort

FILE_BASIC_INFORMATION

FILE_COMPLETION_INFORMATION

FILE_DISPOSITION_INFORMATION

FILE_END_OF_FILE_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_LINK_INFORMATION

FILE_NAME_INFORMATION

FILE_POSITION_INFORMATION

FILE_RENAME_INFORMATION

FILE_VALID_DATA_LENGTH_INFORMATION

ZwClose

ZwCreateFile

ZwOpenFile

ZwQueryInformationFile