Código de controle FSCTL_FILE_LEVEL_TRIM

Artigo
06/25/2024

O código de controle FSCTL_FILE_LEVEL_TRIM fornece um método para cortar intervalos de dados em um arquivo. Os intervalos de corte de arquivos são convertidos para o dispositivo de armazenamento subjacente, permitindo que ele otimize sua organização de recursos para melhorar o desempenho do acesso. Uma solicitação FSCTL_FILE_LEVEL_TRIM permite que um arquivo de disco virtual permaneça alocado em um tamanho fixo enquanto corta o armazenamento físico para corresponder aos intervalos de dados liberados no disco virtual.

Para executar essa operação, chame FltFsControlFile or ZwFsControlFile com os seguintes parâmetros.

Parâmetros

Instância [in]: somente FltFsControlFile. Ponteiro de instância opaco para o autor da chamada. Esse parâmetro é necessário e não pode ser NULL.
FileObject [in]: somente FltFsControlFile. O ponteiro do objeto para o arquivo que tem os dados a serem cortados. Esse parâmetro é necessário e não pode ser NULL.
FileHandle [in]: somente ZwFsControlFile. O identificador do arquivo que tem os dados a serem cortados. Esse parâmetro é necessário e não pode ser NULL.
FsControlCode [in]: código de controle da operação. Use FSCTL_FILE_LEVEL_TRIM para esta operação.
InputBuffer [in]: um ponteiro para uma estrutura FILE_LEVEL_TRIM que contém uma matriz de intervalos de corte do arquivo.
InputBufferLength [in]: o tamanho, em bytes, do buffer apontado pelo parâmetro InputBuffer. Esse valor deve ter pelo menos (FILE_LEVEL_TRIM).
OutputBuffer [out]: um ponteiro para uma estrutura FILE_LEVEL_TRIM_OUTPUT opcional que recebe o resultado da operação de corte.
OutputBufferLength [out]: o tamanho, em bytes, do buffer apontado pelo parâmetro OutputBuffer. Esse valor deve ser pelo menos sizeof(FILE_LEVEL_TRIM_OUTPUT) se FILE_LEVEL_TRIM_OUTPUT estiver incluído em OutputBuffer. Caso contrário, defina-o como 0.

Bloqueio de status

FltFsControlFile ou ZwFsControlFile retorna STATUS_SUCCESS ou possivelmente um dos valores a seguir.

Código	Significado
STATUS_INVALID_PARAMETER	O arquivo a ser cortado é compactado ou criptografado, o comprimento do buffer de entrada ou saída é inválido ou nenhum intervalo de corte é especificado.
STATUS_INSUFFICIENT_RESOURCES	Falha na alocação de recursos internos.
STATUS_FILE_LOCK_CONFLICT	Um intervalo de corte faz parte de um intervalo de bytes bloqueado anteriormente.
STATUS_VOLUME_DISMOUNTED	O volume onde o arquivo reside não está montado.
STATUS_PURGE_FAILED	Uma limpeza de cache falhou para um intervalo de corte.
STATUS_NO_RANGES_PROCESSED	Nenhum intervalo na matriz de intervalo de corte foi processado.

Comentários

A execução de cortes em determinados dispositivos de armazenamento pode melhorar significativamente o desempenho de gravações futuras. O corte também retorna recursos para o pool de alocação em sistemas de armazenamento que são pouco provisionados. Quando os arquivos são excluídos em um disco virtual, o tamanho do próprio arquivo de disco virtual não é alterado. Os intervalos de dados liberados no disco virtual não são cortados no armazenamento físico em que o arquivo de disco virtual reside. Um dispositivo de disco virtual pode notificar o sistema de arquivos de que determinados intervalos de dados em um arquivo de disco virtual podem ser cortados no dispositivo de armazenamento físico com uma solicitação FSCTL_FILE_LEVEL_TRIM. O sistema de arquivos emitirá uma solicitação de corte para o armazenamento físico. Uma solicitação FSCTL_FILE_LEVEL_TRIM também pode ser emitida por aplicativos de serviço que gerenciam arquivos de troca de banco de dados ou memória.

O código de controle FSCTL_FILE_LEVEL_TRIM tentará cortar os intervalos de bytes selecionados de um arquivo de um dispositivo de armazenamento. Os intervalos de bytes estão contidos na matriz Ranges na estrutura FILE_LEVEL_TRIM. Incluídas na matriz Intervalos estão uma ou mais estruturas FILE_LEVEL_TRIM_RANGE.

Incluir intervalos sobrepostos na matriz de intervalo não é necessariamente uma condição de erro. Isso depende de como o processamento de extensão é tratado pelo armazenamento subjacente.

Os intervalos cortados são limpos como páginas do cache do sistema de arquivos. Para corresponder ao tamanho da página do cache, o comprimento de um intervalo de corte é reduzido para um múltiplo de PAGE_SIZE. Além disso, se um deslocamento de intervalo de corte não começar em um limite de página, ele será alinhado ao limite da página seguinte. Com essas restrições, os comprimentos do intervalo de corte serão reduzidos quando seus deslocamentos não estiverem alinhados à página ou os comprimentos não forem múltiplos do tamanho de página. Um comprimento de intervalo de corte pode ser reduzido para 0 se o comprimento original for inferior a duas páginas e o deslocamento não estiver alinhado à página.

Se um intervalo de corte for especificado ou a página ajustada além do fim do arquivo (EOF), o intervalo será ignorado. No entanto, um deslocamento de intervalo alinhado antes do EOF, mas com um comprimento que se estende além do EOF, será ajustado para um múltiplo do tamanho de página <= EOF.

Não há suporte para corte no nível do arquivo para arquivos compactados ou criptografados (arquivos com atributos ATTRIBUTE_FLAG_COMPRESSION_MASK ou ATTRIBUTE_FLAG_ENCRYPTED definidos).

Um corte de arquivo é executado fora de qualquer transação. A operação de corte não pode ser revertida.

Com arquivos esparsos (arquivos com o atributo ATTRIBUTE_FLAG_SPARSE definido), um intervalo de corte em uma parte não alocada do arquivo é ignorado.

Quando incluído no OutputBuffer, o membro NumRangesProcessed do FILE_LEVEL_TRIM_OUTPUT indicará o número de intervalos de corte processados com êxito. Se ocorrer um erro durante o processamento dos intervalos de corte, NumRangesProcessed especificará o índice inicial dos intervalos não processados restantes, terminando no membro NumRanges de FILE_LEVEL_TRIM - 1.