FSCTL_SET_SPARSE IOCTL (winioctl.h)
Marca o arquivo indicado como esparso ou não esparso. Em um arquivo esparso, grandes intervalos de zeros podem não exigir alocação de disco. O espaço para dados diferentes de zero será alocado conforme necessário à medida que o arquivo for gravado.
Para executar essa operação, chame a função DeviceIoControl com os parâmetros a seguir.
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
);
Comentários
Para obter as implicações de E/S sobreposta nesta operação, consulte a seção Comentários de DeviceIoControl.
O código de controle FSCTL_SET_SPARSE define ou limpa o atributo FILE_ATTRIBUTE_SPARSE_FILE do arquivo especificado.
Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Uma operação clara é válida somente em arquivos que não têm mais regiões esparsas. A execução de uma operação clara em um arquivo com regiões esparsas pode ter resultados imprevisíveis. Você pode determinar se há regiões esparsas em um arquivo usando o código de controle FSCTL_QUERY_ALLOCATED_RANGES .
Se o parâmetro lpInBuffer for NULL, a operação se comportará da mesma forma que se o membro SetSparse da estrutura FILE_SET_SPARSE_BUFFER fosse TRUE. Em outras palavras, a operação define o arquivo como um arquivo esparso.
Windows Server 2003 e Windows XP: Se uma estrutura FILE_SET_SPARSE_BUFFER for passada no parâmetro lpInBuffer , o único valor válido para o membro SetSparse será TRUE, que define o arquivo como um arquivo esparso. Passar FALSE na estrutura FILE_SET_SPARSE_BUFFER fará com que essa chamada de função falhe. A única maneira de limpar esse atributo é substituir o arquivo (por exemplo, chamando a função CreateFile pelo sinalizador CREATE_ALWAYS ).
Não é possível criar um arquivo esparso chamando CreateFile com FILE_ATTRIBUTE_SPARSE_FILE no parâmetro dwFlagsAndAttributes . Você deve usar o código de controle FSCTL_SET_SPARSE .
Observe que os carimbos de data/hora podem não ser atualizados corretamente para um arquivo remoto. Para garantir resultados consistentes, use E/S sem buffer.
No Windows 8 e no Windows Server 2012, esse código é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | Sim |
| TFO (Failover transparente) do SMB 3.0 | Sim |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | Consulte Comentário |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Os CsvFs farão E/S redirecionada para arquivos esparsos. CsvFs permite tornar o arquivo esparso somente quando o arquivo é aberto exclusivamente por um nó. O Failover Transparente do SMB 3.0 não dá suporte à gravação em buffer.
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho | winioctl.h (inclua Windows.h) |