FSCTL_SET_SPARSE IOCTL (winioctl.h)
将指示的文件标记为稀疏或不稀疏。 在稀疏文件中，较大的零范围可能不需要磁盘分配。 写入文件时，将根据需要分配非零数据的空间。
若要执行此操作，请使用以下参数调用 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 透明故障转移 (TFO) | 是 |
| 具有横向扩展文件共享的 SMB 3.0 (SO) | 是 |
| 群集共享卷文件系统 (CSV) | 请参阅注释 |
| 弹性文件系统 (ReFS) | 是 |
CsvF 将对稀疏文件执行重定向的 IO。 仅当文件由节点以独占方式打开时，CsvFs 才允许使文件稀疏。 SMB 3.0 透明故障转移不支持缓冲写入。
要求
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 标头 | winioctl.h (包括 Windows.h) |