code de contrôle FSCTL_FILE_LEVEL_TRIM

Article
02/02/2024

Le code de contrôle FSCTL_FILE_LEVEL_TRIM fournit une méthode pour couper les plages de données avec dans un fichier. Les plages de découpage de fichiers sont traduites en périphérique de stockage sous-jacent, ce qui lui permet d’optimiser ses organization de ressources pour améliorer les performances d’accès. Une demande de FSCTL_FILE_LEVEL_TRIM permet à un fichier de disque virtuel de rester alloué à une taille fixe tout en réduisant le stockage physique pour qu’il corresponde 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 de instance opaque pour l’appelant. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.
FileObject [in] : FltFsControlFile uniquement. Pointeur de l’objet fichier vers le fichier contenant les données à découper. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.
FileHandle [in] : ZwFsControlFile uniquement. Handle de fichier du fichier qui contient les données à découper. Ce paramètre est obligatoire et ne peut pas avoir la valeur 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écoupage pour le fichier.
InputBufferLength [in] : taille, en octets, de la mémoire tampon vers laquelle pointe 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, de la mémoire tampon vers laquelle pointe le paramètre OutputBuffer . Cette valeur doit être au moins sizeof(FILE_LEVEL_TRIM_OUTPUT) si FILE_LEVEL_TRIM_OUTPUT est inclus dans OutputBuffer. Sinon, cette valeur est définie sur 0.

Bloc d’état

FltFsControlFile ou ZwFsControlFile retourne 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 trim fait partie d’une plage d’octets précédemment verrouillée.
STATUS_VOLUME_DISMOUNTED	Le volume dans lequel réside le fichier n’est pas monté.
STATUS_PURGE_FAILED	Une purge du cache a échoué pour une plage de découpage.
STATUS_NO_RANGES_PROCESSED	Aucune plage du tableau de plages de découpage n’a été traitée.

Remarques

L’exécution du découpage sur certains appareils de stockage peut améliorer considérablement leurs performances d’écriture futures. Trim retourne également des ressources au pool d’allocation dans les systèmes de stockage qui sont provisionnés de manière mince. Lorsque des fichiers sont supprimés sur un disque virtuel, la taille du fichier de disque virtuel lui-même n’est pas modifiée. Les plages de données libérées sur le disque virtuel ne sont pas rogées sur le stockage physique où réside le fichier de disque virtuel. Un périphérique de disque virtuel peut informer le système de fichiers que certaines plages de données d’un fichier de disque virtuel peuvent être supprimées sur l’appareil de stockage physique avec une demande de FSCTL_FILE_LEVEL_TRIM . Le système de fichiers émettra ensuite une demande de rognage au stockage physique. Une demande de FSCTL_FILE_LEVEL_TRIM peut également être émise par les applications de service qui gèrent des fichiers d’échange de base de données ou de mémoire.

Le code de contrôle FSCTL_FILE_LEVEL_TRIM tente de réduire les plages d’octets sélectionnées d’un fichier à partir d’un périphérique de stockage. Les plages d’octets sont contenues dans le tableau Ranges de la structure FILE_LEVEL_TRIM . Le tableau Ranges comprend une ou plusieurs structures FILE_LEVEL_TRIM_RANGE .

L’inclusion de plages de chevauchement 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 supprimées sont purgées en tant que pages du cache du système de fichiers. Pour correspondre à la taille de la page du cache, la longueur d’une plage de découpages est ajusté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 de plage de coupe diminuent lorsque leurs décalages ne sont pas alignés sur la page ou que les longueurs ne sont pas un multiple de taille de page. La longueur d’une plage de découpages peut être réduite à 0 si la longueur d’origine est inférieure à deux pages et si le décalage n’est pas aligné sur la page.

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

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

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 les fichiers partiellement alloués (fichiers avec l’ensemble d’attributs ATTRIBUTE_FLAG_SPARSE ), une plage de découpage dans une partie non allouée du fichier est ignorée.

Lorsqu’il est inclus dans OutputBuffer, le membre NumRangesProcessed du FILE_LEVEL_TRIM_OUTPUT indique le nombre de plages de découpage traitées avec succès. Si une erreur se produit pendant le traitement des plages de découpage, 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.