FSCTL_SET_SPARSE (Compact 2013)

3/26/2014

This I/O control marks the specified file as sparse. In a sparse file, large ranges of zeros may not require disk allocation. Space for nonzero data is allocated as needed as the file is written.

Syntax

BOOL DeviceIoControl(
    HANDLE hDevice,           // handle to device
    DWORD dwIoControlCode,    // use FSCTL_SET_SPARSE
    LPVOID lpInBuffer,        // pointer to input buffer
    DWORD nInBufferSize,      // input buffer size
    LPVOID lpOutBuffer,       // pointer to output buffer
    DWORD nOutBufferSize,     // output buffer size
    LPDWORD lpBytesReturned,  // number of bytes returned
    OVERLAPPED lpOverlapped   // pointer to OVERLAPPED structure
);

Parameters

• hDevice
  [in] Handle to the file or alternate stream to be made sparse. To obtain a handle, call the CreateFile function.

• dwIoControlCode
  [in] Set to FSCTL_SET_SPARSE.

• lpInBuf
  Not used. Set to NULL.

• nInBufSize
  Not used. Set to zero.

• lpOutBuf
  Not used. Set to NULL.

• nOutBufSize
  Not used. Set to NULL.

• lpBytesReturned
  [out] Pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

• lpOverlapped
  Not used.

Return Values

If the operation succeeds, the DeviceIoControl function returns a nonzero value. If the operation fails, DeviceIoControl returns zero. For extended error information, call GetLastError.

Remarks

This I/O control sets the FILE_ATTRIBUTE_SPARSE_FILE attribute of the specified file. The only way to clear this attribute is to overwrite the file, for example, by calling the CreateFile function with the CREATE_ALWAYS flag.

Requirements

See Also

Reference

FS I/O Controls
CreateFile

Other Resources

DeviceIoControl