SetFileValidData 関数 (fileapi.h)

  • [アーティクル]

指定したファイルの有効なデータ長を設定します。 この関数は、非常に限られたシナリオで役立ちます。 詳細については、「解説」を参照してください。

注意 この機能を適切なセキュリティ上の考慮事項なしで使用すると、データのプライバシーとセキュリティが損なわれる可能性があります。 詳細については、「解説」を参照してください。

 

構文

BOOL SetFileValidData(
  [in] HANDLE   hFile,
  [in] LONGLONG ValidDataLength
);

パラメーター

[in] hFile

ファイルへのハンドル。 ファイルは、 GENERIC_WRITE アクセス権を持ち、 SE_MANAGE_VOLUME_NAME 特権が有効になっている状態で開かれている必要があります。 詳細については、「 ファイル のセキュリティとアクセス権」を参照してください。

メモ ファイルをネットワーク ファイルにしたり、圧縮、スパース、またはトランザクションにすることはできません。
 

[in] ValidDataLength

新しい有効なデータ長。

このパラメーターは、現在の有効なデータ長より大きく、現在のファイル サイズより小さい正の値である必要があります。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合、戻り値は 0 になります。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

SetFileValidData 関数は、ファイルの論理終了を設定します。 ファイルのサイズを設定するには、 SetEndOfFile 関数を使用します。 物理ファイル サイズは、ファイルの末尾とも呼ばれます。

各ファイル ストリームには、次のプロパティがあります。

  • ファイル サイズ: ファイル内のデータのバイトまでのサイズ。
  • 割り当てサイズ: ディスク上のファイルに割り当てられる領域のサイズ。これは、常にクラスター サイズの偶数倍です。
  • 有効なデータ長: 実際にバイトに書き込まれるファイル内のデータの長さ。 この値は、常にファイル サイズ以下です。
通常、 SetFileValidData 関数は、システム レベルのアプリケーションが独自のプライベート データで使用します。 すべてのファイル システムで有効なデータ長が使用されるわけではありません。 一部のファイル システムでは、複数の有効なデータ範囲を追跡できます。 一般に、ほとんどのアプリケーションでこの関数を呼び出す必要はありません。

SetFileValidData 関数を使用すると、ファイルに非量子的に書き込むときに、データにゼロを入力しないようにすることができます。 関数は、ファイルに書き込まずにファイル内のデータを有効にします。 その結果、パフォーマンスが向上する可能性がありますが、以前の既存のファイルのディスク上の既存のデータが意図しないリーダーで誤って使用できるようになる可能性があります。 次の段落では、この潜在的なセキュリティとプライバシーの問題について詳しく説明します。

呼び出し元は、最初にファイルを開くときに SE_MANAGE_VOLUME_NAME 特権を有効にする必要があります。 アプリケーションは、SE_MANAGE_VOLUME_NAMEアクセス権を持つエンティティへのアクセスを制限するファイルに対してのみ SetFileValidData を呼び出す必要があります。 アプリケーションでは、ファイルの書き込みされていない範囲が公開されないようにする必要があります。または、セキュリティの問題が次のように発生する可能性があります。

SetFileValidData がファイルで使用されている場合、ファイルに割り当てられたクラスターにゼロを入力しないことによって、潜在的なパフォーマンス向上が得られます。 したがって、ファイルから読み取ると、割り当てられたクラスターに含まれるもの 、他のユーザーからのコンテンツが返される可能性があります。 呼び出し元は SetFileValidData を成功させるためにSE_MANAGE_VOLUME_NAME特権を持っている必要があり、ディスク上のすべてのデータをそのようなユーザーが読み取ることができるため、これは必ずしもセキュリティ上の問題ではありません。 ただし、この呼び出し元は、次の場合に SE_MANAGE_VOLUME_PRIVILEGE 特権を取得できない他のユーザーに、このデータを誤って公開する可能性があります。

  • 他のリーダーを拒否する共有モードでファイルが開かれていた場合、特権のないユーザーはファイルを開いて、公開されたデータを読み取ることができます。
  • 呼び出し元が呼び出しで指定された ValidDataLength の書き込みを終了する前にシステムが応答を停止した場合、再起動時に、そのような特権のないユーザーはファイルを開き、公開されたコンテンツを読み取ることができます。

SetFileValidData の呼び出し元が適切に制限されたアクセス制御でファイルを開いた場合、前の条件は適用されません。 ただし、 SetFileValidData で拡張された部分的に書き込まれたファイル (つまり、呼び出しで指定された ValidDataLength まで書き込みが完了しなかった) には、プライバシーまたはセキュリティの潜在的な脆弱性がもう 1 つ存在します。 管理者は、制限の厳しい ACL アクセス許可で適切に制御されていないターゲットにファイルをコピーできるため、拡張領域のデータが不正な読み取りに誤って公開される可能性があります。

以下で説明するように、パフォーマンスに関する考慮事項に加えて、 SetFileValidData が汎用の使用には推奨されないのは、このような理由です。

セキュリティとアクセス権限の詳細については、「 特別な特権を使用した実行 」および「 ファイル セキュリティとアクセス権」を参照してください。

SetFileValidData 関数を使用すると、非常に特殊な状況で大きなファイルを作成し、後続のファイル I/O のパフォーマンスを他の方法よりも優れたパフォーマンスにすることができます。 具体的には、ファイルの拡張部分が大きく、データベースの種類のアプリケーションのようにランダムに書き込まれる場合、 SetEndOfFile を使用してランダムに書き込むよりも、ファイルの拡張と書き込みに要する時間が短縮されます。 他のほとんどの状況では、 通常、SetFileValidData を使用してもパフォーマンスが向上せず、パフォーマンスが低下する可能性があります。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (ReFS) はい

要件

   
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー fileapi.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

File Management 関数

SetEndOfFile