Share via

setFileValidData 函数 (fileapi.h)

  • 项目

设置指定文件的有效数据长度。 此函数在非常有限的方案中有用。 有关详细信息，请参见“备注”部分。

谨慎 如果不考虑适当的安全注意事项使用此功能，可能会损害数据隐私和安全性。 有关详细信息，请参阅“备注”部分。

 

语法

BOOL SetFileValidData(
  [in] HANDLE   hFile,
  [in] LONGLONG ValidDataLength
);

参数

[in] hFile

文件的句柄。 文件必须已使用 GENERIC_WRITE 访问权限打开，并且已启用 SE_MANAGE_VOLUME_NAME 特权。 有关详细信息，请参阅 文件安全性和访问权限。

注意 该文件不能是网络文件，也不能是压缩、稀疏或事务处理。
 

[in] ValidDataLength

新的有效数据长度。

此参数必须是大于当前有效数据长度但小于当前文件大小的正值。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，返回值为 0。 要获得更多的错误信息，请调用 GetLastError。

注解

SetFileValidData 函数设置文件的逻辑端。 若要设置文件的大小，请使用 SetEndOfFile 函数。 物理文件大小也称为文件末尾。

每个文件流具有以下属性：

  • 文件大小：文件中数据的大小（字节）。
  • 分配大小：为磁盘上的文件分配的空间大小，始终是群集大小的偶数倍。
  • 有效数据长度：实际写入到 字节的文件中的数据长度。 此值始终小于或等于文件大小。
通常， SetFileValidData 函数由系统级应用程序在其自己的专用数据上使用。 并非所有文件系统都使用有效的数据长度。 某些文件系统可以跟踪多个有效数据范围。 通常，大多数应用程序将永远不需要调用此函数。

通过 SetFileValidData 函数，可以在以非排队方式写入文件时避免使用零填充数据。 函数使文件中的数据有效，而无需写入文件。 因此，尽管可能会实现一些性能提升，但以前现有文件中的磁盘上的现有数据可能会无意中提供给意外的读取者。 以下段落提供了此潜在安全和隐私问题的更详细说明。

调用方在最初打开文件时必须启用 SE_MANAGE_VOLUME_NAME 特权。 应用程序应仅对限制访问具有SE_MANAGE_VOLUME_NAME访问权限的实体的文件调用 SetFileValidData。 应用程序必须确保永远不会公开文件的未写入范围，否则可能会导致安全问题，如下所示。

如果对文件使用 SetFileValidData ，则通过不用零填充文件分配的群集来获得潜在的性能提升。 因此，从文件读取将返回分配的群集包含的任何内容，可能来自其他用户的内容。 此时，这不一定是安全问题，因为调用方需要具有 setFileValidDataSE_MANAGE_VOLUME_NAME权限才能成功，并且磁盘上的所有数据都可以由此类用户读取。 但是，如果存在以下条件，则此调用方可能会无意中将此数据公开给无法获取 SE_MANAGE_VOLUME_PRIVILEGE 特权的其他用户：

  • 如果文件未使用拒绝其他读取者共享模式打开，则非特权用户可以打开它并读取公开的数据。
  • 如果系统在调用方完成写入调用中提供的 ValidDataLength 之前停止响应，则在重新启动时，此类非特权用户可以打开文件并读取公开的内容。

如果 SetFileValidData 的调用方打开了具有足够限制的访问控制的文件，则上述条件将不适用。 但是，对于使用 SetFileValidData 扩展的部分写入文件 (即，在调用中提供的 ValidDataLength) 还存在另一个潜在的隐私或安全漏洞时，写入尚未完成。 管理员可以将文件复制到未使用限制性 ACL 权限正确控制的目标，从而无意中将扩展区域的数据公开给未经授权的读取。

出于这些原因，除了性能注意事项外，不建议将 SetFileValidData 用于常规用途，如下所述。

有关安全和访问权限的详细信息，请参阅 使用特殊权限运行 和 文件安全和访问权限。

可以使用 SetFileValidData 函数在非常特定的情况下创建大型文件，以便后续文件 I/O 的性能可以优于其他方法。 具体而言，如果文件的扩展部分很大，并且将随机写入（例如在数据库类型的应用程序中），则扩展和写入文件所需的时间将比使用 SetEndOfFile 和随机写入要快。 在大多数其他情况下，使用 SetFileValidData 通常不会提高性能，有时可能会降低性能。

在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。

技术 支持
服务器消息块 (SMB) 3.0 协议 是
SMB 3.0 透明故障转移 (TFO) 是
具有横向扩展文件共享的 SMB 3.0 (SO) 是
群集共享卷文件系统 (CSV) 是
弹性文件系统 (ReFS) 是

要求

   
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 fileapi.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

文件管理函数

SetEndOfFile