| 1 |
.\" Copyright 2000-2007, Andreas Grünbacher <[email protected]> |
| 2 |
.\" Copyright 2001-2007, Silicon Graphics, Inc. |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 6 |
.\" |
| 7 |
.TH xattr 7 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
xattr \- Extended attributes |
| 10 |
.SH DESCRIPTION |
| 11 |
Extended attributes are name:value pairs associated permanently with |
| 12 |
files and directories, similar to the environment strings associated |
| 13 |
with a process. |
| 14 |
An attribute may be defined or undefined. |
| 15 |
If it is defined, its value may be empty or non-empty. |
| 16 |
.P |
| 17 |
Extended attributes are extensions to the normal attributes which are |
| 18 |
associated with all inodes in the system (i.e., the |
| 19 |
.BR stat (2) |
| 20 |
data). |
| 21 |
They are often used to provide additional functionality |
| 22 |
to a filesystem\[em]for example, additional security features such as |
| 23 |
Access Control Lists (ACLs) may be implemented using extended attributes. |
| 24 |
.P |
| 25 |
Users with search access to a file or directory may use |
| 26 |
.BR listxattr (2) |
| 27 |
to retrieve a list of attribute names defined for that file or directory. |
| 28 |
.P |
| 29 |
Extended attributes are accessed as atomic objects. |
| 30 |
Reading |
| 31 |
.RB ( getxattr (2)) |
| 32 |
retrieves the whole value of an attribute and stores it in a buffer. |
| 33 |
Writing |
| 34 |
.RB ( setxattr (2)) |
| 35 |
replaces any previous value with the new value. |
| 36 |
.P |
| 37 |
Space consumed for extended attributes may be counted towards the disk quotas |
| 38 |
of the file owner and file group. |
| 39 |
.SS Extended attribute namespaces |
| 40 |
Attribute names are null-terminated strings. |
| 41 |
The attribute name is always specified in the fully qualified |
| 42 |
.I namespace.attribute |
| 43 |
form, for example, |
| 44 |
.IR user.mime_type , |
| 45 |
.IR trusted.md5sum , |
| 46 |
.IR system.posix_acl_access , |
| 47 |
or |
| 48 |
.IR security.selinux . |
| 49 |
.P |
| 50 |
The namespace mechanism is used to define different classes of extended |
| 51 |
attributes. |
| 52 |
These different classes exist for several reasons; |
| 53 |
for example, the permissions |
| 54 |
and capabilities required for manipulating extended attributes of one |
| 55 |
namespace may differ to another. |
| 56 |
.P |
| 57 |
Currently, the |
| 58 |
.IR security , |
| 59 |
.IR system , |
| 60 |
.IR trusted , |
| 61 |
and |
| 62 |
.I user |
| 63 |
extended attribute classes are defined as described below. |
| 64 |
Additional classes may be added in the future. |
| 65 |
.SS Extended security attributes |
| 66 |
The security attribute namespace is used by kernel security modules, |
| 67 |
such as Security Enhanced Linux, and also to implement file capabilities (see |
| 68 |
.BR capabilities (7)). |
| 69 |
Read and write access permissions to security attributes depend on the |
| 70 |
policy implemented for each security attribute by the security module. |
| 71 |
When no security module is loaded, all processes have read access to |
| 72 |
extended security attributes, and write access is limited to processes |
| 73 |
that have the |
| 74 |
.B CAP_SYS_ADMIN |
| 75 |
capability. |
| 76 |
.SS System extended attributes |
| 77 |
System extended attributes are used by the kernel to store system |
| 78 |
objects such as Access Control Lists. |
| 79 |
Read and write |
| 80 |
access permissions to system attributes depend on the policy implemented |
| 81 |
for each system attribute implemented by filesystems in the kernel. |
| 82 |
.SS Trusted extended attributes |
| 83 |
Trusted extended attributes are visible and accessible only to processes that |
| 84 |
have the |
| 85 |
.B CAP_SYS_ADMIN |
| 86 |
capability. |
| 87 |
Attributes in this class are used to implement mechanisms in user |
| 88 |
space (i.e., outside the kernel) which keep information in extended attributes |
| 89 |
to which ordinary processes should not have access. |
| 90 |
.SS User extended attributes |
| 91 |
User extended attributes may be assigned to files and directories for |
| 92 |
storing arbitrary additional information such as the mime type, |
| 93 |
character set or encoding of a file. |
| 94 |
The access permissions for user |
| 95 |
attributes are defined by the file permission bits: |
| 96 |
read permission is required to retrieve the attribute value, |
| 97 |
and writer permission is required to change it. |
| 98 |
.P |
| 99 |
The file permission bits of regular files and directories are |
| 100 |
interpreted differently from the file permission bits of special files |
| 101 |
and symbolic links. |
| 102 |
For regular files and directories the file |
| 103 |
permission bits define access to the file's contents, while for device special |
| 104 |
files they define access to the device described by the special file. |
| 105 |
The file permissions of symbolic links are not used in access checks. |
| 106 |
These differences would allow users to consume filesystem resources in |
| 107 |
a way not controllable by disk quotas for group or world writable |
| 108 |
special files and directories. |
| 109 |
.P |
| 110 |
For this reason, |
| 111 |
user extended attributes are allowed only for regular files and directories, |
| 112 |
and access to user extended attributes is restricted to the |
| 113 |
owner and to users with appropriate capabilities for directories with the |
| 114 |
sticky bit set (see the |
| 115 |
.BR chmod (1) |
| 116 |
manual page for an explanation of the sticky bit). |
| 117 |
.SS Filesystem differences |
| 118 |
The kernel and the filesystem may place limits on the maximum number |
| 119 |
and size of extended attributes that can be associated with a file. |
| 120 |
The VFS-imposed limits on attribute names and values are 255 bytes |
| 121 |
and 64\ kB, respectively. |
| 122 |
The list of attribute names that |
| 123 |
can be returned is also limited to 64\ kB |
| 124 |
(see BUGS in |
| 125 |
.BR listxattr (2)). |
| 126 |
.P |
| 127 |
Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), |
| 128 |
require the filesystem to be mounted with the |
| 129 |
.B user_xattr |
| 130 |
mount option in order for user extended attributes to be used. |
| 131 |
.P |
| 132 |
In the current ext2, ext3, and ext4 filesystem implementations, |
| 133 |
the total bytes used by the names and values of all of a file's |
| 134 |
extended attributes must fit in a single filesystem block (1024, 2048 |
| 135 |
or 4096 bytes, depending on the block size specified when the |
| 136 |
filesystem was created). |
| 137 |
.P |
| 138 |
In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no |
| 139 |
practical limit on the number of extended attributes |
| 140 |
associated with a file, and the algorithms used to store extended |
| 141 |
attribute information on disk are scalable. |
| 142 |
.P |
| 143 |
In the JFS, XFS, and Reiserfs filesystem implementations, |
| 144 |
the limit on bytes used in an EA value is the ceiling imposed by the VFS. |
| 145 |
.P |
| 146 |
In the Btrfs filesystem implementation, |
| 147 |
the total bytes used for the name, value, and implementation overhead bytes |
| 148 |
is limited to the filesystem |
| 149 |
.I nodesize |
| 150 |
value (16\ kB by default). |
| 151 |
.SH STANDARDS |
| 152 |
Extended attributes are not specified in POSIX.1, but some other systems |
| 153 |
(e.g., the BSDs and Solaris) provide a similar feature. |
| 154 |
.SH NOTES |
| 155 |
Since the filesystems on which extended attributes are stored might also |
| 156 |
be used on architectures with a different byte order and machine word |
| 157 |
size, care should be taken to store attribute values in an |
| 158 |
architecture-independent format. |
| 159 |
.P |
| 160 |
This page was formerly named |
| 161 |
.BR attr (5). |
| 162 |
.\" .SH AUTHORS |
| 163 |
.\" Andreas Gruenbacher, |
| 164 |
.\" .RI < [email protected] > |
| 165 |
.\" and the SGI XFS development team, |
| 166 |
.\" .RI < [email protected] >. |
| 167 |
.SH SEE ALSO |
| 168 |
.BR attr (1), |
| 169 |
.BR getfattr (1), |
| 170 |
.BR setfattr (1), |
| 171 |
.BR getxattr (2), |
| 172 |
.BR FS_IOC_GETFLAGS (2const), |
| 173 |
.BR FS_IOC_SETFLAGS (2const), |
| 174 |
.BR listxattr (2), |
| 175 |
.BR removexattr (2), |
| 176 |
.BR setxattr (2), |
| 177 |
.BR acl (5), |
| 178 |
.BR capabilities (7), |
| 179 |
.BR selinux (8) |