Функция SetFileAttributesA (fileapi.h)

Статья
06/02/2023

Задает атрибуты для файла или каталога.

Чтобы выполнить эту операцию как транзакцию, используйте функцию SetFileAttributesTransacted .

Синтаксис

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

Параметры

[in] lpFileName

Имя файла, атрибуты которого необходимо задать.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

[in] dwFileAttributes

Атрибуты файла, которые необходимо задать для файла.

Этот параметр может быть одним или несколькими значениями, объединенными с помощью побитового оператора ИЛИ. Однако все остальные значения переопределяют FILE_ATTRIBUTE_NORMAL.

Эта функция поддерживает не все атрибуты. Дополнительные сведения см. в разделе «Примечания».

Ниже приведен список поддерживаемых значений атрибутов.

Значение	Значение
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Файл или каталог, который является архивным файлом или каталогом. Приложения обычно используют этот атрибут для пометки файлов для резервного копирования или удаления.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Файл или каталог скрыты. Он не включается в обычный список каталогов.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Файл, для которых не заданы другие атрибуты. Этот атрибут действителен только при использовании отдельно.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 8192 (0x2000)	Файл или каталог не должны индексироваться службой индексирования содержимого.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Данные файла доступны не сразу. Этот атрибут указывает, что данные файла физически перемещаются в автономное хранилище. Этот атрибут используется удаленным хранилищем, которое является программным обеспечением для управления иерархическим хранилищем. Приложения не должны произвольно изменять этот атрибут.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Файл, доступный только для чтения. Приложения могут читать файл, но не могут записывать в него или удалять его. Этот атрибут не учитывается в каталогах. Дополнительные сведения см. в разделе Невозможно просматривать или изменять атрибуты папок только для чтения или Системные атрибуты в Windows Server 2003, Windows XP или Windows Vista.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Файл или каталог, часть или который используется исключительно операционной системой.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Файл, используемый для временного хранения. Если доступно достаточно памяти кэша, файловые системы избегают записи данных обратно в хранилище, так как обычно приложение удаляет временный файл после закрытия дескриптора. В этом сценарии система может полностью избежать записи данных. В противном случае данные записываются после закрытия дескриптора.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

В следующей таблице описано, как задать атрибуты, которые нельзя задать с помощью атрибутов SetFileAttributes. Полный список всех значений атрибутов файла и их описания см. в разделе Константы атрибутов файлов.

attribute	Настройка
FILE_ATTRIBUTE_COMPRESSED 0x800	Чтобы задать состояние сжатия файла, используйте функцию DeviceIoControl с операцией FSCTL_SET_COMPRESSION .
FILE_ATTRIBUTE_DEVICE 0x40	Защищены; не использовать.
FILE_ATTRIBUTE_DIRECTORY 0x10	Файлы нельзя преобразовать в каталоги. Чтобы создать каталог, используйте функцию CreateDirectory или CreateDirectoryEx .
FILE_ATTRIBUTE_ENCRYPTED 0x4000	Чтобы создать зашифрованный файл, используйте функцию CreateFile с атрибутом FILE_ATTRIBUTE_ENCRYPTED . Чтобы преобразовать существующий файл в зашифрованный, используйте функцию EncryptFile .
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Чтобы связать точку повторного аналитики с файлом или каталогом, используйте функцию DeviceIoControl с операцией FSCTL_SET_REPARSE_POINT .
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Чтобы задать разреженный атрибут файла, используйте функцию DeviceIoControl с операцией FSCTL_SET_SPARSE .

Транзакция операций

Если файл открыт для изменения в транзакции, ни один другой поток не может открыть файл для изменения, пока транзакция не будет зафиксирована. Таким образом, если транзакционный поток открывает файл первым, все последующие потоки, которые пытаются изменить файл до фиксации транзакции, получат нарушение общего доступа. Если поток без транзакций изменяет файл до того, как выполняется транзакция, и файл по-прежнему открыт, когда транзакция пытается открыть его, транзакция получает ошибку ERROR_TRANSACTIONAL_CONFLICT.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

Пример см. в разделе Извлечение и изменение атрибутов файла.

Примечание

Заголовок fileapi.h определяет SetFileAttributes в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll