FSCTL_FILE_LEVEL_TRIM-Steuercode

Artikel
06/28/2024

Der Steuercode FSCTL_FILE_LEVEL_TRIM bietet eine Methode zum Trimmen von Datenbereichen in einer Datei. Die Datei-Trimmbereiche werden auf das zugrundeliegende Gerät übertragen und bieten ihm die Möglichkeit, seine Organisation der Ressourcen zu optimieren, um die Zugriffsleistung zu verbessern. Eine FSCTL_FILE_LEVEL_TRIM-Abfrage bietet die Möglichkeit, einer virtuellen Datenträgerdatei eine feste Größe zuzuweisen und gleichzeitig den physischen Speicher so zu trimmen, dass er den auf dem virtuellen Datenträger freigegebenen Datenbereichen entspricht.

Um diesen Vorgang durchzuführen, rufen Sie FltFsControlFile oder ZwFsControlFile mit den folgenden Parametern auf.

Parameter

Instance [in]: Nur FltFsControlFile. Nicht transparenter Instanz-Zeiger für den Aufrufer. Dieser Parameter ist erforderlich und kann nicht NULL sein.
FileObject [in]: Nur FltFsControlFile. Der Datei-Objekt-Zeiger auf die Datei, die die zu trimmenden Daten enthält. Dieser Parameter ist erforderlich und kann nicht NULL sein.
FileHandle [in]: Nur ZwFsControlFile. Der Dateihandle der Datei, die die zu trimmenden Daten enthält. Dieser Parameter ist erforderlich und kann nicht NULL sein.
FsControlCode [in]: Steuercode für den Vorgang. Verwenden Sie FSCTL_FILE_LEVEL_TRIM für diesen Vorgang.
InputBuffer [in]: Ein Zeiger auf eine FILE_LEVEL_TRIM-Struktur, die ein Array von Trimmbereichen für die Datei enthält.
InputBufferLength [in]: Größe des Puffers in Bytes, auf den der Parameter InputBuffer zeigt. Dieser Wert muss mindestens sizeof(FILE_LEVEL_TRIM) betragen.
OutputBuffer [out]: Ein Zeiger auf eine optionale FILE_LEVEL_TRIM_OUTPUT-Struktur, die das Ergebnis des Vorgangs Trim erhält.
OutputBufferLength [out]: Größe des Puffers in Bytes, auf den der Parameter OutputBuffer zeigt. Dieser Wert muss mindestens sizeof(FILE_LEVEL_TRIM_OUTPUT) betragen, wenn FILE_LEVEL_TRIM_OUTPUT in OutputBuffer enthalten ist. Andernfalls wird dieser Wert auf 0 festgelegt.

Statusblock

FltFsControlFile oder ZwFsControlFile gibt STATUS_SUCCESS oder möglicherweise einen der folgenden Werte zurück.

Code	Bedeutung
STATUS_INVALID_PARAMETER	Die zu trimmende Datei ist entweder komprimiert oder verschlüsselt, die Länge des Eingabe- oder Ausgabepuffers ist ungültig oder es sind keine Trimmbereiche angegeben.
STATUS_INSUFFICIENT_RESOURCES	Eine interne Ressourcenzuweisung ist fehlgeschlagen.
STATUS_FILE_LOCK_CONFLICT	Ein Trimmbereich ist Teil eines zuvor gesperrten Bytebereichs.
STATUS_VOLUME_DISMOUNTED	Das Volume, auf dem sich die Datei befindet, ist nicht gemountet.
STATUS_PURGE_FAILED	Die Bereinigung des Caches für einen Trimmbereich ist fehlgeschlagen.
STATUS_NO_RANGES_PROCESSED	Es wurden keine Bereiche im Trimmbereich-Array verarbeitet.

Hinweise

Die Durchführung eines Trimmvorgangs auf bestimmten Speichern kann deren zukünftige Schreibleistung erheblich verbessern. In Speichersystemen mit Thinly Provisioning gibt das Trimmverfahren auch Ressourcen an den Pool zurück. Wenn Dateien auf einem virtuellen Datenträger gelöscht werden, wird die Größe der Datei auf dem virtuellen Datenträger selbst nicht verändert. Die auf dem virtuellen Datenträger freigegebenen Datenbereiche werden auf dem physischen Speicher, auf dem sich die Datei des virtuellen Datenträgers befindet, nicht beschnitten. Ein Gerät mit virtuellem Datenträger kann dem Dateisystem mit einer FSCTL_FILE_LEVEL_TRIM-Anfrage mitteilen, dass bestimmte Datenbereiche in einer virtuellen Datenträger-Datei auf dem physischen Speicher getrimmt werden können. Das Dateisystem wird dann eine Trimmanforderung an den physischen Speicher senden. Eine FSCTL_FILE_LEVEL_TRIM-Anforderung kann auch von Dienstanwendungen ausgegeben werden, die Datenbank- oder Speicherauslagerungsdateien verwalten.

Der Code FSCTL_FILE_LEVEL_TRIM versucht, die ausgewählten Byte-Bereiche einer Datei von einem Speicher-Gerät zu trimmen. Die Bytebereiche sind in dem Array Ranges in der Struktur FILE_LEVEL_TRIM enthalten. In dem Array Ranges sind eine oder mehrere FILE_LEVEL_TRIM_RANGE-Strukturen enthalten.

Die Aufnahme von sich überschneidenden Bereichen in das Ranges-Array ist nicht unbedingt eine Fehlerbedingung. Dies hängt davon ab, wie die Verarbeitung von Bereichen durch den zugrunde liegenden Speicher gehandhabt wird.

Getrimmte Bereiche werden als Seiten aus dem Dateisystem-Cache gelöscht. Um mit der Seitengröße des Caches übereinzustimmen, wird die Länge eines getrimmten Bereichs auf ein Vielfaches von PAGE_SIZE reduziert. Wenn der Offset eines Trimmbereichs nicht an einer Seitengrenze beginnt, wird er an der nächsten Seitengrenze ausgerichtet. Mit diesen Einschränkungen werden die Längen von Trimmbereichen reduziert, wenn ihre Offsets nicht an der Seite ausgerichtet sind oder die Längen nicht ein Vielfaches der Seitengröße sind. Die Länge eines Trimmbereichs kann sich auf 0 reduzieren, wenn die ursprüngliche Länge weniger als zwei Seiten beträgt und der Offset nicht an einer Seite ausgerichtet ist.

Wenn ein Trimmbereich jenseits des End-of-File (EOF) angegeben oder an einer Seite ausgerichtet ist, wird der Bereich ignoriert. Ein Offset-Bereich, der vor EOF ausgerichtet ist, aber eine Länge hat, die über EOF hinausgeht, wird jedoch auf ein Vielfaches der Seitengröße <= EOF angepasst.

Trimmen auf Dateiebene wird nicht für komprimierte oder verschlüsselte Dateien unterstützt (Dateien mit den Attributen ATTRIBUTE_FLAG_COMPRESSION_MASK oder ATTRIBUTE_FLAG_ENCRYPTED festgelegt).

Eine Dateitrimmung wird außerhalb einer Transaktion durchgeführt. Der Trimmvorgang kann nicht rückgängig gemacht werden.

Bei Sparse-Dateien (Dateien, für die das Attribut ATTRIBUTE_FLAG_SPARSE festgelegt ist) wird ein Trimmbereich in einem nicht zugewiesenen Teil der Datei ignoriert.

Wenn es in OutputBuffer enthalten ist, zeigt das NumRangesProcessed-Mitglied der FILE_LEVEL_TRIM_OUTPUT die Anzahl der erfolgreich verarbeiteten Trimmbereiche an. Tritt bei der Verarbeitung der Trimmbereiche ein Fehler auf, gibt NumRangesProcessed den Startindex der verbleibenden unverarbeiteten Bereiche an, der beim NumRanges-Mitglied von FILE_LEVEL_TRIM - 1 endet.