Código de control FSCTL_FILE_LEVEL_TRIM

Artículo
06/28/2024

El código de control FSCTL_FILE_LEVEL_TRIM proporciona un método para recortar intervalos de datos en un archivo. Los intervalos de recorte de archivos se traducen al dispositivo de almacenamiento subyacente, lo que le permite optimizar su organización de recursos para mejorar el rendimiento del acceso. Una solicitud FSCTL_FILE_LEVEL_TRIM permite que un archivo de disco virtual permanezca asignado con un tamaño fijo mientras se recorta el almacenamiento físico para que se corresponda con los intervalos de datos liberados en el disco virtual.

Para realizar esta operación, llame a FltFsControlFile o ZwFsControlFile con los parámetros siguientes.

Parámetros

Instance [in]: FltFsControlFile únicamente. Puntero de instancia opaco para el llamador. Este parámetro es obligatorio y no puede ser NULL.
FileObject [in]: FltFsControlFile únicamente. Puntero del objeto de archivo al archivo que tiene los datos que se van a recortar. Este parámetro es obligatorio y no puede ser NULL.
FileHandle [in]: ZwFsControlFile únicamente. Identificador de archivo del archivo que tiene los datos que se van a recortar. Este parámetro es obligatorio y no puede ser NULL.
FsControlCode [in]: Código de control para la operación. Use FSCTL_FILE_LEVEL_TRIM para esta operación.
InputBuffer [in]: puntero a una estructura FILE_LEVEL_TRIM que contiene una matriz de intervalos de recorte para el archivo.
InputBufferLength [in]: tamaño, en bytes, del búfer al que apunta el parámetro InputBuffer. Este valor debe ser al menos sizeof(FILE_LEVEL_TRIM).
OutputBuffer [out]: puntero a una estructura FILE_LEVEL_TRIM_OUTPUT opcional que recibe el resultado de la operación de recorte.
OutputBufferLength [out]: tamaño, en bytes, del búfer al que apunta el parámetro OutputBuffer. Este valor debe ser al menos sizeof(FILE_LEVEL_TRIM_OUTPUT) si FILE_LEVEL_TRIM_OUTPUT se incluye en OutputBuffer. De lo contrario, se establece como 0.

Bloque de estados

FltFsControlFile o ZwFsControlFile devuelve STATUS_SUCCESS o posiblemente uno de los siguientes valores.

Código	Significado
STATUS_INVALID_PARAMETER	El archivo que se va a recortar está comprimido o cifrado, la longitud del búfer de entrada o salida no es válida o, no se especifica ningún intervalo de recorte.
STATUS_INSUFFICIENT_RESOURCES	Error en la asignación de recursos internos.
STATUS_FILE_LOCK_CONFLICT	Un intervalo de recorte forma parte de un intervalo de bytes bloqueado previamente.
STATUS_VOLUME_DISMOUNTED	El volumen donde reside el archivo no está montado.
STATUS_PURGE_FAILED	Error de purga de caché para un intervalo de recorte.
STATUS_NO_RANGES_PROCESSED	No se procesaron intervalos en la matriz de intervalos de recorte.

Comentarios

El recorte en determinados dispositivos de almacenamiento puede mejorar significativamente su rendimiento de escritura futuro. El recorte también devuelve recursos al grupo de asignación en sistemas de almacenamiento que se aprovisionan de forma fina. Cuando los archivos se eliminan en un disco virtual, no se cambia el tamaño del propio archivo de disco virtual. Los intervalos de datos liberados en el disco virtual no se recortan en el almacenamiento físico donde reside el archivo de disco virtual. Un dispositivo de disco virtual puede notificar al sistema de archivos que determinados intervalos de datos de un archivo de disco virtual se pueden recortar en el dispositivo de almacenamiento físico con una solicitud FSCTL_FILE_LEVEL_TRIM. Después, el sistema de archivos emitirá una solicitud de recorte al almacenamiento físico. Las aplicaciones de servicio que administran archivos de intercambio de memoria o base de datos también pueden emitir una solicitud FSCTL_FILE_LEVEL_TRIM.

El código de control FSCTL_FILE_LEVEL_TRIM intentará recortar los intervalos de bytes seleccionados de un archivo desde un dispositivo de almacenamiento. Los intervalos de bytes se encuentran en la matriz Ranges de la estructura FILE_LEVEL_TRIM. En la matriz Ranges se incluyen una o varias estructuras FILE_LEVEL_TRIM_RANGE.

La inclusión de intervalos superpuestos en la matriz de intervalos no es necesariamente una condición de error. Esto depende del modo en que el almacenamiento subyacente controla el procesamiento de la extensión.

Los intervalos recortados se purgan como páginas de la caché del sistema de archivos. Para que coincida con el tamaño de la página de caché, la longitud de un intervalo de recorte se ajusta a un múltiplo de PAGE_SIZE. Además, si un desplazamiento del intervalo de recorte no comienza en un límite de página, se alinea con el límite de la página siguiente. Con estas restricciones, las longitudes de intervalo de recorte se reducirán cuando sus desplazamientos no estén alineados con páginas o las longitudes no sean múltiplos del tamaño de página. Una longitud del intervalo de recorte puede reducirse a 0 si la longitud original es inferior a dos páginas y el desplazamiento no está alineado con páginas.

Si se especifica un intervalo de recorte o se ajusta una página más allá del final del archivo (EOF), se omite el intervalo. Sin embargo, un desplazamiento de intervalo alineado antes de EOF, pero que tenga una longitud extendida más allá de EOF se ajustará a un múltiplo de tamaño de página <= EOF.

No se admite el recorte de nivel de archivo para archivos comprimidos o cifrados (archivos con los atributos ATTRIBUTE_FLAG_COMPRESSION_MASK o ATTRIBUTE_FLAG_ENCRYPTED establecidos).

Un recorte de archivos se realiza fuera de cualquier transacción. No se puede revertir la operación de recorte.

Con archivos dispersos (archivos con el conjunto de atributos ATTRIBUTE_FLAG_SPARSE), se omite un intervalo de recorte en una parte sin asignar del archivo.

Cuando se incluye en OutputBuffer, el miembro NumRangesProcessed de FILE_LEVEL_TRIM_OUTPUT indicará el número de intervalos de recorte procesados correctamente. Si se produce un error durante el procesamiento de los intervalos de recorte, NumRangesProcessed especificará el índice inicial de los intervalos no procesados restantes, finalizando en el miembro NumRanges de FILE_LEVEL_TRIM - 1.