Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

FSCTL_SET_SPARSE control code

Marks the indicated file as sparse or not sparse. In a sparse file, large ranges of zeros may not require disk allocation. Space for nonzero data will be allocated as needed as the file is written.

To perform this operation, call the DeviceIoControl function with the following parameters.


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

Parameters

hDevice

A handle to the file or alternate stream to be made sparse. To retrieve a file handle, use the CreateFile function. The file must be opened with either write permission or with the FILE_FLAG_BACKUP_SEMANTICS flag. For more information, see File Security and Access Rights.

This operation cannot be called with a directory or volume handle.

dwIoControlCode

The control code for the operation. Use FSCTL_SET_SPARSE for this operation.

lpInBuffer

A pointer to the set sparse flag, contained in FILE_SET_SPARSE_BUFFER. This parameter is optional and can be NULL.

Windows Server 2003 and Windows XP:  Some modes of operation are unsupported. For more information, see the Remarks section.

nInBufferSize

The size of the input buffer in bytes. If lpInBuffer is NULL, this parameter must be zero.

lpOutBuffer

Not used with this operation; set to NULL.

nOutBufferSize

Not used with this operation; set to zero.

lpBytesReturned

A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation returns no output data and lpOutBuffer is NULL, DeviceIoControl makes use of lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation has completed. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

A pointer to an OVERLAPPED structure.

If hDevice was opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.

For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.

Return value

If the operation completes successfully, DeviceIoControl returns a nonzero value.

If the operation fails or is pending, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of DeviceIoControl.

The FSCTL_SET_SPARSE control code sets or clears the FILE_ATTRIBUTE_SPARSE_FILE attribute of the specified file.

Windows Server 2008 R2, Windows 7, Windows Server 2008, and Windows Vista:  A clear operation is valid only on files that no longer have any sparse regions. Performing a clear operation on a file with sparse regions can have unpredictable results.

You can determine whether there are any sparse regions in a file by using the FSCTL_QUERY_ALLOCATED_RANGES control code.

If the lpInBuffer parameter is NULL, the operation will behave the same as if the SetSparse member of the FILE_SET_SPARSE_BUFFER structure were TRUE. In other words, the operation sets the file to a sparse file.

Windows Server 2003 and Windows XP:  If a FILE_SET_SPARSE_BUFFER structure is passed in the lpInBuffer parameter, the only valid value for the SetSparse member is TRUE, which sets the file to a sparse file. Passing FALSE in the FILE_SET_SPARSE_BUFFER structure will cause this function call to fail. The only way to clear this attribute is to overwrite the file (for example, by calling the CreateFile function with the CREATE_ALWAYS flag).

You cannot create a sparse file by calling CreateFile with FILE_ATTRIBUTE_SPARSE_FILE in the dwFlagsAndAttributes parameter. You must use the FSCTL_SET_SPARSE control code.

Note that the time stamps may not be updated correctly for a remote file. To ensure consistent results, use unbuffered I/O.

In Windows 8 and Windows Server 2012, this code is supported by the following technologies.

TechnologySupported

Server Message Block (SMB) 3.0 protocol

Yes

SMB 3.0 Transparent Failover (TFO)

Yes

SMB 3.0 with Scale-out File Shares (SO)

Yes

Cluster Shared Volume File System (CsvFS)

See Comment

Resilient File System (ReFS)

Yes

 

CsvFs will do redirected IO for sparse files. CsvFs allows making file sparse only when the file is opened exclusively by a node. SMB 3.0 Transparent Failover does not support buffered write."

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

WinIoCtl.h (include Windows.h)

See also

DeviceIoControl
File Management Control Codes
FILE_SET_SPARSE_BUFFER
FSCTL_QUERY_ALLOCATED_RANGES
FSCTL_SET_ZERO_DATA
Sparse Files

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.