Compartilhar via


Função SetFileValidData (fileapi.h)

Define o comprimento de dados válido do arquivo especificado. Esta função é útil em cenários muito limitados. Para obter mais informações, consulte a seção Comentários.

Cuidado O uso dessa função sem considerações de segurança adequadas pode comprometer a privacidade e a segurança dos dados. Para obter mais informações, consulte a seção Comentários.

 

Sintaxe

BOOL SetFileValidData(
  [in] HANDLE   hFile,
  [in] LONGLONG ValidDataLength
);

Parâmetros

[in] hFile

Um manipulador para o arquivo. O arquivo deve ter sido aberto com o direito de acesso GENERIC_WRITE e o privilégio de SE_MANAGE_VOLUME_NAME habilitado. Para obter mais informações, consulte Segurança de arquivo e direitos de acesso.

Nota O arquivo não pode ser um arquivo de rede ou ser compactado, esparso ou transacionado.
 

[in] ValidDataLength

O novo comprimento de dados válido.

Esse parâmetro deve ser um valor positivo maior que o comprimento de dados válido atual, mas menor que o tamanho do arquivo atual.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será 0. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função SetFileValidData define o final lógico de um arquivo. Para definir o tamanho de um arquivo, use a função SetEndOfFile . O tamanho do arquivo físico também é conhecido como o final do arquivo.

Cada fluxo de arquivos tem as seguintes propriedades:

  • Tamanho do arquivo: o tamanho dos dados em um arquivo, para o byte.
  • Tamanho da alocação: o tamanho do espaço alocado para um arquivo em um disco, que é sempre um múltiplo par do tamanho do cluster.
  • Comprimento de dados válido: o comprimento dos dados em um arquivo que é realmente gravado, no byte. Esse valor é sempre menor ou igual ao tamanho do arquivo.
Normalmente, a função SetFileValidData é usada por aplicativos no nível do sistema em seus próprios dados privados. Nem todos os sistemas de arquivos usam comprimento de dados válido. Alguns sistemas de arquivos podem acompanhar vários intervalos de dados válidos. Em geral, a maioria dos aplicativos nunca precisará chamar essa função.

A função SetFileValidData permite evitar o preenchimento de dados com zeros ao gravar não sequencialmente em um arquivo. A função torna os dados no arquivo válidos sem gravar no arquivo. Como resultado, embora algum ganho de desempenho possa ser realizado, os dados existentes em disco de arquivos existentes anteriormente podem inadvertidamente ficar disponíveis para leitores não intencionais. Os parágrafos a seguir fornecem uma descrição mais detalhada desse possível problema de segurança e privacidade.

Um chamador deve ter o privilégio SE_MANAGE_VOLUME_NAME habilitado ao abrir um arquivo inicialmente. Os aplicativos devem chamar SetFileValidData somente em arquivos que restringem o acesso a essas entidades que têm acesso SE_MANAGE_VOLUME_NAME . O aplicativo deve garantir que os intervalos não escritos do arquivo nunca sejam expostos ou que os problemas de segurança possam resultar da seguinte maneira.

Se SetFileValidData for usado em um arquivo, o ganho de desempenho potencial será obtido por não preencher os clusters alocados para o arquivo com zeros. Portanto, a leitura do arquivo retornará tudo o que os clusters alocados contêm, potencialmente conteúdo de outros usuários. Isso não é necessariamente um problema de segurança neste momento, porque o chamador precisa ter SE_MANAGE_VOLUME_NAME privilégio para Que SetFileValidData tenha êxito e todos os dados no disco possam ser lidos por esses usuários. No entanto, esse chamador pode expor inadvertidamente esses dados a outros usuários que não podem adquirir o privilégio SE_MANAGE_VOLUME_PRIVILEGE se o seguinte for válido:

  • Se o arquivo não tiver sido aberto com um modo de compartilhamento que nega outros leitores, um usuário sem privilégios poderá abri-lo e ler os dados expostos.
  • Se o sistema parar de responder antes que o chamador termine de gravar o ValidDataLength fornecido na chamada, em uma reinicialização, um usuário sem privilégios poderá abrir o arquivo e ler o conteúdo exposto.

Se o chamador de SetFileValidData abrisse o arquivo com controle de acesso adequadamente restritivo, as condições anteriores não se aplicariam. No entanto, para arquivos parcialmente gravados estendidos com SetFileValidData (ou seja, a gravação não foi concluída até o ValidDataLength fornecido na chamada) existe mais uma possível vulnerabilidade de privacidade ou segurança. Um administrador pode copiar o arquivo para um destino que não é controlado corretamente com permissões de ACL restritivas, expondo inadvertidamente os dados da área estendida à leitura não autorizada.

É por esses motivos que SetFileValidData não é recomendado para uso de uso geral, além de considerações de desempenho, conforme discutido abaixo.

Para obter mais informações sobre privilégios de segurança e acesso, consulte Executando com privilégios especiais e segurança de arquivos e direitos de acesso.

Você pode usar a função SetFileValidData para criar arquivos grandes em circunstâncias muito específicas para que o desempenho de E/S de arquivo subsequente possa ser melhor do que outros métodos. Especificamente, se a parte estendida do arquivo for grande e for gravada aleatoriamente, como em um tipo de banco de dados de aplicativo, o tempo necessário para estender e gravar no arquivo será mais rápido do que usar SetEndOfFile e gravar aleatoriamente. Na maioria das outras situações, geralmente não há ganho de desempenho para usar SetFileValidData e, às vezes, pode haver uma penalidade de desempenho.

No Windows 8 e Windows Server 2012, essa função é 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) Sim
ReFS (Sistema de Arquivos Resiliente) Sim

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]
Plataforma de Destino Windows
Cabeçalho fileapi.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

Funções de gerenciamento de arquivos

SetEndOfFile