FSCTL_FILE_LEVEL_TRIM 制御コード
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 配列には、1 つ以上の FILE_LEVEL_TRIM_RANGE 構造体が含まれます。
範囲配列に重複する範囲が含まれていても、必ずしもエラー状態であるとは限りません。 これは、基になるストレージによってエクステント処理がどのように処理されるかによって異なります。
トリミングされた範囲は、ファイル システム キャッシュからページとして消去されます。 キャッシュ ページ サイズと一致するように、トリミング範囲の長さは PAGE_SIZE の倍数に調整されます。 また、トリミング範囲のオフセットがページ境界から始まらない場合は、次のページ境界に揃えられます。 これらの制約により、トリミング範囲の長さは、オフセットがページに揃えられていない場合、または長さがページ サイズの倍数でない場合に減少します。 元の長さが 2 ページ未満で、オフセットがページに揃えられていない場合、トリミング範囲の長さは 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 メンバーで終わる、残りの未処理範囲の開始インデックスを指定します。
要件
| 要件タイプ | 要件 |
|---|---|
| サポートされている最小のクライアント | Windows 8 |
| ヘッダー | Ntifs.h (Ntifs.hまたは Fltkernel.h を含む) |