FSCTL_FILE_LEVEL_TRIM 控制代码

项目
06/28/2024

FSCTL_FILE_LEVEL_TRIM 控制代码提供了一种剪裁文件中数据范围的方法。文件剪裁范围被转换到基础存储设备，使其能够优化资源组织，提高访问性能。 FSCTL_FILE_LEVEL_TRIM 请求允许虚拟磁盘文件保持固定大小的分配，同时根据虚拟磁盘释放的数据范围对物理存储进行剪裁。

要执行此操作，请使用以下参数调用 FltFsControlFile 或 ZwFsControlFile。

参数

实例 [in]：仅 FltFsControlFile。调用方的不透明实例指针。该参数为必填且不能为 NULL。
FileObject [in]：仅 FltFsControlFile。文件对象指针，指向包含待剪裁数据的文件。该参数为必填且不能为 NULL。
FileHandle [in]：仅 ZwFsControlFile。要剪裁数据的文件的文件句柄。该参数为必填且不能为 NULL。
FsControlCode [in]：操作的控制代码。使用 FSCTL_FILE_LEVEL_TRIM 进行此操作。
InputBuffer [in]：指向 FILE_LEVEL_TRIM 结构的指针，该结构包含一个文件剪裁范围数组。
InputBufferLength [in]：以字节为单位指定 InputBuffer 参数指向的缓冲区的大小。该值必须至少是 sizeof(FILE_LEVEL_TRIM) 的值。
OutputBuffer [out]：指向可选 FILE_LEVEL_TRIM_OUTPUT 结构的指针，该结构接收剪裁操作的结果。
OutputBufferLength [out]：以字节为单位指定 OutputBuffer 参数指向的缓冲区的大小。如果 FILE_LEVEL_TRIM_OUTPUT 包含在 OutputBuffer 中，该值必须至少为 sizeof(FILE_LEVEL_TRIM_OUTPUT)。否则，这将设置为 0。

状态块

FltFsControlFile 或 ZwFsControlFile 返回 STATUS_SUCCESS 或下列可能的值之一。

代码	含义
STATUS_INVALID_PARAMETER	要剪裁的文件已压缩或加密，输入或输出缓冲区长度无效，或未指定剪裁范围。
STATUS_INSUFFICIENT_RESOURCES	内部资源分配失败。
STATUS_FILE_LOCK_CONFLICT	剪裁范围是先前锁定的字节范围的一部分。
STATUS_VOLUME_DISMOUNTED	文件所在的卷未加载。
STATUS_PURGE_FAILED	剪裁范围的缓存清除失败。
STATUS_NO_RANGES_PROCESSED	未处理剪裁范围数组中的任何范围。

注解

对某些存储设备进行剪裁可以显著提高其未来的写入性能。在精简预配的存储系统中，Trim 还会将资源返回分配池。在删除虚拟磁盘上的文件时，虚拟磁盘文件本身的大小不会改变。虚拟磁盘上释放的数据范围不会在虚拟磁盘文件所在的物理存储上进行剪裁。虚拟磁盘设备可通过 FSCTL_FILE_LEVEL_TRIM 请求，通知文件系统可在物理存储设备上剪裁虚拟磁盘文件中的某些数据范围。然后，文件系统会向物理存储发出剪裁请求。管理数据库或内存交换文件的服务应用程序也可能发出 FSCTL_FILE_LEVEL_TRIM 请求。

FSCTL_FILE_LEVEL_TRIM 控制代码将尝试从存储设备中剪裁文件的选定字节范围。字节范围包含在 FILE_LEVEL_TRIM 结构中的 Ranges 数组中。 Ranges 数组中包含一个或多个 FILE_LEVEL_TRIM_RANGE 结构。

在范围数组中包含重叠的范围并不一定是错误条件。这取决于基础存储如何处理盘区处理。

经过剪裁的范围会作为页面从文件系统缓存中清除。为了与缓存页面大小相匹配，剪裁范围的长度会被调整为 PAGE_SIZE 的倍数。此外，如果剪裁范围偏移不是从页面边界开始，则会与下一个页面边界对齐。有了这些限制条件，当偏移量未与页面对齐或长度不是页面大小的倍数时，剪裁范围长度就会减少。如果原始长度小于两页，且偏移未进行页面对齐，则剪裁范围长度可能会减至 0。

如果指定了剪裁范围或页面调整超出了文件末尾 (EOF)，则该范围将被忽略。但是，在 EOF 之前对齐但长度超过 EOF 的范围偏移将被调整为 <= EOF 的页面大小倍数。

压缩或加密文件（设置了 ATTRIBUTE_FLAG_COMPRESSION_MASK 或 ATTRIBUTE_FLAG_ENCRYPTED 属性的文件）不支持文件级剪裁。

文件剪裁在任何事务之外执行的。剪裁操作无法回滚。

对于稀疏文件（设置了 ATTRIBUTE_FLAG_SPARSE 属性的文件），文件未分配部分的剪裁范围将被忽略。

如果包含在 OutputBuffer 中，FILE_LEVEL_TRIM_OUTPUT 中的 NumRangesProcessed 成员将显示成功处理的剪裁范围数。如果在处理修剪范围时发生错误，NumRangesProcessed 将指定剩余未处理范围的起始索引，以 FILE_LEVEL_TRIM - 1 中的 NumRanges 成员为终点。