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 DELETE 标志在 DesiredAccess 参数中设置的文件打开。
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标志。 此值从版本 1803 Windows 10开始可用。
FileLinkInformation (72) 创建指向现有文件的硬链接,该文件在 FILE_LINK_INFORMATION 结构中指定。 并非所有文件系统都支持硬链接;例如,NTFS 在 FAT 不执行时执行。
FileCaseSensitiveInformationForceAccessCheck (75) 更改 FILE_CASE_SENSITIVE_INFORMATION 结构中提供的信息。 调用方必须打开文件,并在 DesiredAccess 参数中设置FILE_WRITE_ATTRIBUTES标志。 这是 FileCaseSensitiveInformation 操作的特殊版本,用于强制 IOManager 对内核模式驱动程序执行访问检查,类似于应用于用户模式调用方的检查。 此操作只能由 IOManager 识别,文件系统绝不应接收它。 此值从版本 1803 Windows 10开始可用。
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”。

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

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 ntifs.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅“备注”部分)
DDI 符合性规则 HwStorPortProhibitedDDIs,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