NtSetInformationFile 函数（ntifs.h）

项目
02/07/2025

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 结构中指定。并非所有文件系统都支持硬链接;例如，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_INFORMATION 的 EndOfFile 成员指定了当前文件标记之外的偏移量，NtSetInformationFile 扩展文件并将扩展名填充为零。

有关处理文件的详细信息，请参阅在驱动程序中使用文件。

NtSetInformationFile 的调用方必须在 IRQL = PASSIVE_LEVEL，启用了特殊内核 APC。

注意

如果在用户模式下调用此函数，请使用名称“NtSetInformationFile”而不是“ZwSetInformationFile”。

对于内核模式驱动程序的调用，NtXxx 和 ZwXxx 版本的 Windows 本机系统服务例程的行为方式可能以不同的方式处理和解释输入参数。有关 NtXxx**** 与例程的 ZwXxx**** 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求	价值
最低支持的客户端	Windows 2000。
目标平台	普遍
标头	ntifs.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
库	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL（请参阅“备注”部分）
DDI 符合性规则	HwStorPortProhibitedDDI、PowerIrpDDis