SetFileAttributesW 函数（fileapi.h）

项目
11/20/2024

设置文件或目录的属性。

若要将此操作作为事务处理操作执行，请使用 SetFileAttributesTransacted 函数。

语法

BOOL SetFileAttributesW(
  [in] LPCWSTR lpFileName,
  [in] DWORD   dwFileAttributes
);

参数

[in] lpFileName

要设置其属性的文件的名称。

默认情况下，名称限制为MAX_PATH个字符。若要将此限制扩展到 32,767 宽字符，请将“\\？\”前面追加到路径。有关详细信息，请参阅命名文件、路径和命名空间。

提示

从 Windows 10 版本 1607 开始，你可以选择加入以删除MAX_PATH限制，而无需追加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

[in] dwFileAttributes

要为文件设置的文件属性。

此参数可以是一个或多个值，使用按位 OR 运算符组合。但是，所有其他值都替代 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设置无法设置的属性。有关所有文件属性值及其说明的完整列表，请参阅文件属性常量。

属性	如何设置
FILE_ATTRIBUTE_COMPRESSED 0x800	若要设置文件的压缩状态，请将 DeviceIoControl 函数与 FSCTL_SET_COMPRESSION 操作一起使用。
FILE_ATTRIBUTE_DEVICE 0x40	保留;请勿使用。
FILE_ATTRIBUTE_DIRECTORY 0x10	无法将文件转换为目录。若要创建目录，请使用 CreateDirectory 或 CreateDirectoryEx 函数。
FILE_ATTRIBUTE_ENCRYPTED 0x4000	若要创建加密文件，请使用具有 FILE_ATTRIBUTE_ENCRYPTED 属性的 CreateFile 函数。若要将现有文件转换为加密文件，请使用 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 协议	是的
SMB 3.0 透明故障转移（TFO）	是的
具有横向扩展文件共享的 SMB 3.0 （SO）	是的
群集共享卷文件系统（CsvFS）	是的
可复原文件系统（ReFS）	是的

例子

有关示例，请参阅检索和更改文件属性。

注意

fileapi.h 标头将 SetFileAttributes 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows XP [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	fileapi.h （包括 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll