Code de contrôle FSCTL_FILE_LEVEL_TRIM

Article
07/01/2024

Le code de contrôle FSCTL_FILE_LEVEL_TRIM fournit une méthode pour découper des plages de données dans un fichier. Les plages de découpage du fichier sont transmises à l’unité de stockage sous-jacente, ce qui lui permet d’optimiser l’organisation de ses ressources afin d’améliorer les performances d’accès. Une demande FSCTL_FILE_LEVEL_TRIM permet à un fichier de disque virtuel de rester alloué avec une taille fixe tout en réduisant le stockage physique pour correspondre aux plages de données libérées sur le disque virtuel.

Pour effectuer cette opération, appelez FltFsControlFile ou ZwFsControlFile avec les paramètres suivants.

Paramètres

Instance [in] : FltFsControlFile uniquement. Pointeur d’instance opaque pour l’appelant. Ce paramètre est requis et ne peut pas être NULL.
FileObject [in] : FltFsControlFile uniquement. Pointeur d’objet de fichier vers le fichier contenant les données à découper. Ce paramètre est requis et ne peut pas être NULL.
FileHandle [in] : ZwFsControlFile uniquement. Handle de fichier du fichier dont les données doivent être découpées. Ce paramètre est requis et ne peut pas être NULL.
FsControlCode [in] : code de contrôle pour l’opération. Utilisez FSCTL_FILE_LEVEL_TRIM pour cette opération.
InputBuffer [in] : pointeur vers une structure FILE_LEVEL_TRIM qui contient un tableau de plages de découpages pour le fichier.
InputBufferLength [in] : taille, en octets, du tampon pointé par le paramètre InputBuffer. Cette valeur doit être au moins sizeof(FILE_LEVEL_TRIM).
OutputBuffer [out] : pointeur vers une structure FILE_LEVEL_TRIM_OUTPUT facultative qui reçoit le résultat de l’opération de découpage.
OutputBufferLength [out] : taille, en octets, du tampon pointé par le paramètre OutputBuffer. Cette valeur doit être au moins sizeof(FILE_LEVEL_TRIM_OUTPUT) if FILE_LEVEL_TRIM_OUTPUT est inclus dans OutputBuffer. Sinon, il es défini sur 0.

Bloc d’état

FltFsControlFile ou ZwFsControlFile renvoie STATUS_SUCCESS ou éventuellement l’une des valeurs suivantes.

Code	Signification
STATUS_INVALID_PARAMETER	Le fichier à découper est compressé ou chiffré, la longueur de la mémoire tampon d’entrée ou de sortie n’est pas valide ou aucune plage de découpage n’est spécifiée.
STATUS_INSUFFICIENT_RESOURCES	Une allocation de ressources interne a échoué.
STATUS_FILE_LOCK_CONFLICT	Une plage de découpages fait partie d’une plage d’octets précédemment verrouillée.
STATUS_VOLUME_DISMOUNTED	Le volume où réside le fichier n’est pas monté.
STATUS_PURGE_FAILED	Un vidage du cache a échoué pour une plage de découpages.
STATUS_NO_RANGES_PROCESSED	Aucune plage du tableau de plages de découpage n’a été traitée.

Notes

L’exécution d’un découpage sur certains appareils de stockage peut améliorer considérablement leurs performances d’écriture. Le découpage renvoie également des ressources dans le pool d’allocations dans les systèmes de stockage qui sont provisionnés de manière dynamique. Lorsque des fichiers sont supprimés sur un disque virtuel, la taille du fichier de ce dernier n’est pas modifiée. Les plages de données libérées sur le disque virtuel ne sont pas supprimées sur le stockage physique où réside le fichier de disque virtuel. Une unité de disque virtuel peut informer le système de fichiers que certaines plages de données dans un fichier de disque virtuel peuvent être découpées sur l’unité de stockage physique avec une demande FSCTL_FILE_LEVEL_TRIM. Le système de fichiers émet ensuite une demande de découpage vers le stockage physique. Une demande de FSCTL_FILE_LEVEL_TRIM peut également être émise par les applications de service gérant des fichiers de base de données ou d’échange de mémoire.

Le code de contrôle FSCTL_FILE_LEVEL_TRIM tentera de découper les plages d’octets sélectionnées d’un fichier à partir d’un appareil de stockage. Les plages d’octets sont contenues dans le tableau Plages de la structure FILE_LEVEL_TRIM. Le tableau Plages comprend une ou plusieurs structures FILE_LEVEL_TRIM_RANGE.

L’inclusion de plages qui se chevauchent dans le tableau de plages n’est pas nécessairement une condition d’erreur. Cela dépend de la façon dont le traitement de l’étendue est géré par le stockage sous-jacent.

Les plages découpées sont vidées en tant que pages du cache du système de fichiers. Pour faire correspondre la taille de la page du cache, la longueur d’une plage de découpage est ramenée à un multiple de PAGE_SIZE. En outre, si un décalage de plage de découpage ne commence pas à une limite de page, il est aligné sur la limite de page suivante. Avec ces contraintes, les longueurs des plages de découpe seront réduites lorsque leurs décalages ne sont pas alignés sur la page ou que les longueurs ne correspondent pas à un multiple de la taille de la page. Une longueur de plage de découpage peut être réduite à 0 si la longueur d’origine est inférieure à deux pages et que le décalage n’est pas aligné sur la page.

Si une plage de découpages est spécifiée ou que la page est ajustée au-delà de la fin du fichier (EOF), elle est ignorée. Toutefois, un décalage de plage aligné avant EOF mais dont la longueur s’étend au-delà de EOF sera ajusté à une taille de page multiple de <= EOF.

Le découpage au niveau du fichier n’est pas pris en charge pour les fichiers compressés ou chiffrés (fichiers avec le jeu d’attributs ATTRIBUTE_FLAG_COMPRESSION_MASK ou ATTRIBUTE_FLAG_ENCRYPTED).

Un découpage de fichier est effectué en dehors de toute transaction. L’opération de découpage ne peut pas être restaurée.

Avec des fichiers partiellement alloués (fichiers avec le jeu d’attributs ATTRIBUTE_FLAG_SPARSE), une plage de découpages dans une partie non allouée du fichier est ignorée.

Lorsqu’il est inclus dans OutputBuffer, le membre NumRangesProcessed de FILE_LEVEL_TRIM_OUTPUT indique le nombre de plages de découpages correctement traitées. Si une erreur se produit pendant le traitement des plages de découpages, NumRangesProcessed spécifie l’index de départ des plages non traitées restantes, se terminant par le membre NumRanges de FILE_LEVEL_TRIM - 1.