FSCTL_SET_SPARSE IOCTL (winioctl.h)

  • [アーティクル]

指定したファイルをスパースまたは非スパースとしてマークします。 スパース ファイルで広範囲が 0 の場合、ディスク割り当ては不要なことがあります。 0 以外のデータの領域は、ファイルの書き込み時に必要に応じて割り当てられます。

この操作を実行するには、次のパラメーターを使用して DeviceIoControl 関数を呼び出します。

BOOL DeviceIoControl(
  (HANDLE) hDevice,                         // handle to a file
  FSCTL_SET_SPARSE,                         // dwIoControlCode
  (PFILE_SET_SPARSE_BUFFER) lpInBuffer,     // input buffer
  (DWORD) nInBufferSize,                    // size of input buffer
  NULL,                                     // lpOutBuffer
  0,                                        // nOutBufferSize
  (LPDWORD) lpBytesReturned,                // number of bytes returned
  (LPOVERLAPPED) lpOverlapped               // OVERLAPPED structure
);

解説

この操作に対する重複した I/O の影響については、 DeviceIoControl の「解説」セクションを参照してください。

FSCTL_SET_SPARSEコントロール コードは、指定したファイルのFILE_ATTRIBUTE_SPARSE_FILE属性を設定またはクリアします。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista: クリア操作は、スパース領域がなくなったファイルでのみ有効です。 スパース領域を含むファイルに対して明確な操作を実行すると、予期しない結果になる可能性があります。 FSCTL_QUERY_ALLOCATED_RANGES制御コードを使用して、ファイル内にスパース領域があるかどうかを判断できます。

lpInBuffer パラメーターが NULL の場合、操作は、FILE_SET_SPARSE_BUFFER構造体の SetSparse メンバーが TRUE の場合と同じように動作します。 つまり、この操作により、ファイルがスパース ファイルに設定されます。

Windows Server 2003 および Windows XP:lpInBuffer パラメーターにFILE_SET_SPARSE_BUFFER構造体が渡された場合、SetSparse メンバーの有効な値は TRUE のみです。これにより、ファイルがスパース ファイルに設定されます。 FILE_SET_SPARSE_BUFFER構造体に FALSE を渡すと、この関数呼び出しが失敗します。 この属性をクリアする唯一の方法は、ファイルを上書きすることです (たとえば、CREATE_ALWAYS フラグを使用して CreateFile 関数を呼び出します)。

dwFlagsAndAttributes パラメーターでFILE_ATTRIBUTE_SPARSE_FILEを使用して CreateFile を呼び出してスパース ファイルを作成することはできません。 FSCTL_SET_SPARSEコントロール コードを使用する必要があります。

リモート ファイルのタイム スタンプが正しく更新されない場合があることに注意してください。 一貫性のある結果を得るには、バッファーなしの I/O を使用します。

Windows 8 および Windows Server 2012 では、このコードは次のテクノロジでサポートされています。

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

CsvFs では、スパース ファイルに対してリダイレクトされた IO が実行されます。 CsvFs では、ファイルがノードによって排他的に開かれている場合にのみ、ファイルをスパースできます。 SMB 3.0 Transparent Failover では、バッファー書き込みがサポートされていません。

要件

   
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
Header winioctl.h (Windows.h を含む)

関連項目