Função SetFileAttributesA (fileapi.h)

Define os atributos de um arquivo ou diretório.

Para executar essa operação como uma operação transacionada, use a função SetFileAttributesTransacted .

Sintaxe

BOOL SetFileAttributesA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes
);

Parâmetros

[in] lpFileName

O nome do arquivo cujos atributos devem ser definidos.

Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres largos, acrescente "\\?\" ao caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

[in] dwFileAttributes

Os atributos a serem definidos para o arquivo.

Esse parâmetro pode ser um ou mais valores, combinados usando o operador OR bit a bit. No entanto, todos os outros valores substituem FILE_ATTRIBUTE_NORMAL.

Nem todos os atributos são compatíveis com essa função. Para obter mais informações, consulte a seção Comentários.

Veja a seguir uma lista de valores de atributo com suporte.

Valor Significado
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
Um arquivo ou diretório que é um arquivo morto ou diretório. Os aplicativos normalmente usam esse atributo para marcar arquivos para backup ou remoção.
FILE_ATTRIBUTE_HIDDEN
2 (0x2)
O arquivo ou diretório está oculto. Ele não está incluído em uma listagem de diretório comum.
FILE_ATTRIBUTE_NORMAL
128 (0x80)
Um arquivo que não tem outros atributos definidos. Esse atributo só é válido quando usado sozinho.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
8192 (0x2000)
O arquivo ou diretório não deve ser indexado pelo serviço de indexação de conteúdo.
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)
Os dados de um arquivo não estão disponíveis imediatamente. Esse atributo indica que os dados do arquivo são movidos fisicamente para o armazenamento offline. Esse atributo é usado pelo Armazenamento Remoto, que é o software de gerenciamento de armazenamento hierárquico. Os aplicativos não devem alterar esse atributo arbitrariamente.
FILE_ATTRIBUTE_READONLY
1 (0x1)
Um arquivo que é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravá-lo ou excluí-lo. Esse atributo não é respeitado em diretórios. Para obter mais informações, confira "Você não pode exibir ou alterar os atributos Somente leitura ou Sistema de pastas no Windows Server 2003, no Windows XP ou no Windows Vista.
FILE_ATTRIBUTE_SYSTEM
4 (0x4)
Um arquivo ou diretório do qual o sistema operacional usa uma parte ou usa exclusivamente.
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)
Um arquivo que está sendo usado para armazenamento temporário. Os sistemas de arquivos evitam gravar dados de volta no armazenamento em massa se houver memória de cache suficiente disponível, pois, normalmente, um aplicativo exclui um arquivo temporário depois que o identificador é fechado. Nesse cenário, o sistema pode evitar totalmente gravar os dados. Caso contrário, os dados serão gravados depois que o identificador for fechado.

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á zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A tabela a seguir descreve como definir os atributos que não podem ser definidos usando SetFileAttributes. Para obter uma lista completa de todos os valores de atributo de arquivo e suas descrições, consulte Constantes de atributo de arquivo.

Atributo Como definir
FILE_ATTRIBUTE_COMPRESSED

0x800

Para definir o estado de compactação de um arquivo, use a função DeviceIoControl com a operação FSCTL_SET_COMPRESSION .
FILE_ATTRIBUTE_DEVICE

0x40

Reservados; não use.
FILE_ATTRIBUTE_DIRECTORY

0x10

Os arquivos não podem ser convertidos em diretórios. Para criar um diretório, use a função CreateDirectory ou CreateDirectoryEx .
FILE_ATTRIBUTE_ENCRYPTED

0x4000

Para criar um arquivo criptografado, use a função CreateFile com o atributo FILE_ATTRIBUTE_ENCRYPTED . Para converter um arquivo existente em um arquivo criptografado, use a função EncryptFile .
FILE_ATTRIBUTE_REPARSE_POINT

0x400

Para associar um ponto de nova análise a um arquivo ou diretório, use a função DeviceIoControl com a operação FSCTL_SET_REPARSE_POINT .
FILE_ATTRIBUTE_SPARSE_FILE

0x200

Para definir o atributo esparso de um arquivo, use a função DeviceIoControl com a operação FSCTL_SET_SPARSE .
 

Operações transacionadas

Se um arquivo estiver aberto para modificação em uma transação, nenhum outro thread poderá abrir o arquivo para modificação até que a transação seja confirmada. Portanto, se um thread transacionado abrir o arquivo primeiro, todos os threads subsequentes que tentarem modificar o arquivo antes que a transação seja confirmada receberão uma violação de compartilhamento. Se um thread não transacionado modificar o arquivo antes do thread transacionado e o arquivo ainda estiver aberto quando a transação tentar abri-lo, a transação receberá o erro ERROR_TRANSACTIONAL_CONFLICT.

Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia Com suporte
Protocolo 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 de cluster (CsvFS) Sim
ReFS (Sistema de Arquivos Resiliente) Sim
 

Exemplos

Para obter um exemplo, consulte Recuperando e alterando atributos de arquivo.

Observação

O cabeçalho fileapi.h define SetFileAttributes como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

   
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho fileapi.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

Constantes de atributo de arquivo

Funções de gerenciamento de arquivos

GetFileAttributes

SetFileAttributesTransacted

Links simbólicos

NTFS transacional