FSCTL_SET_SPARSE IOCTL (winioctl.h)

  • Artigo

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)

Confira também