| .\" Extended attributes manual page |
| .\" |
| .\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher <agruen@suse.de> |
| .\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual. If not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .TH XATTR 7 2020-06-09 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| xattr \- Extended attributes |
| .SH DESCRIPTION |
| Extended attributes are name:value pairs associated permanently with |
| files and directories, similar to the environment strings associated |
| with a process. |
| An attribute may be defined or undefined. |
| If it is defined, its value may be empty or non-empty. |
| .PP |
| Extended attributes are extensions to the normal attributes which are |
| associated with all inodes in the system (i.e., the |
| .BR stat (2) |
| data). |
| They are often used to provide additional functionality |
| to a filesystem\(emfor example, additional security features such as |
| Access Control Lists (ACLs) may be implemented using extended attributes. |
| .PP |
| Users with search access to a file or directory may use |
| .BR listxattr (2) |
| to retrieve a list of attribute names defined for that file or directory. |
| .PP |
| Extended attributes are accessed as atomic objects. |
| Reading |
| .RB ( getxattr (2)) |
| retrieves the whole value of an attribute and stores it in a buffer. |
| Writing |
| .RB ( setxattr (2)) |
| replaces any previous value with the new value. |
| .PP |
| Space consumed for extended attributes may be counted towards the disk quotas |
| of the file owner and file group. |
| .SS Extended attribute namespaces |
| Attribute names are null-terminated strings. |
| The attribute name is always specified in the fully qualified |
| .IR namespace.attribute |
| form, for example, |
| .IR user.mime_type , |
| .IR trusted.md5sum , |
| .IR system.posix_acl_access , |
| or |
| .IR security.selinux . |
| .PP |
| The namespace mechanism is used to define different classes of extended |
| attributes. |
| These different classes exist for several reasons; |
| for example, the permissions |
| and capabilities required for manipulating extended attributes of one |
| namespace may differ to another. |
| .PP |
| Currently, the |
| .IR security , |
| .IR system , |
| .IR trusted , |
| and |
| .IR user |
| extended attribute classes are defined as described below. |
| Additional classes may be added in the future. |
| .SS Extended security attributes |
| The security attribute namespace is used by kernel security modules, |
| such as Security Enhanced Linux, and also to implement file capabilities (see |
| .BR capabilities (7)). |
| Read and write access permissions to security attributes depend on the |
| policy implemented for each security attribute by the security module. |
| When no security module is loaded, all processes have read access to |
| extended security attributes, and write access is limited to processes |
| that have the |
| .B CAP_SYS_ADMIN |
| capability. |
| .SS System extended attributes |
| System extended attributes are used by the kernel to store system |
| objects such as Access Control Lists. |
| Read and write |
| access permissions to system attributes depend on the policy implemented |
| for each system attribute implemented by filesystems in the kernel. |
| .SS Trusted extended attributes |
| Trusted extended attributes are visible and accessible only to processes that |
| have the |
| .B CAP_SYS_ADMIN |
| capability. |
| Attributes in this class are used to implement mechanisms in user |
| space (i.e., outside the kernel) which keep information in extended attributes |
| to which ordinary processes should not have access. |
| .SS User extended attributes |
| User extended attributes may be assigned to files and directories for |
| storing arbitrary additional information such as the mime type, |
| character set or encoding of a file. |
| The access permissions for user |
| attributes are defined by the file permission bits: |
| read permission is required to retrieve the attribute value, |
| and writer permission is required to change it. |
| .PP |
| The file permission bits of regular files and directories are |
| interpreted differently from the file permission bits of special files |
| and symbolic links. |
| For regular files and directories the file |
| permission bits define access to the file's contents, while for device special |
| files they define access to the device described by the special file. |
| The file permissions of symbolic links are not used in access checks. |
| These differences would allow users to consume filesystem resources in |
| a way not controllable by disk quotas for group or world writable |
| special files and directories. |
| .PP |
| For this reason, |
| user extended attributes are allowed only for regular files and directories, |
| and access to user extended attributes is restricted to the |
| owner and to users with appropriate capabilities for directories with the |
| sticky bit set (see the |
| .BR chmod (1) |
| manual page for an explanation of the sticky bit). |
| .SS Filesystem differences |
| The kernel and the filesystem may place limits on the maximum number |
| and size of extended attributes that can be associated with a file. |
| The VFS imposes limitations that an attribute names is limited to 255 bytes |
| and an attribute value is limited to 64\ kB. |
| The list of attribute names that |
| can be returned is also limited to 64\ kB |
| (see BUGS in |
| .BR listxattr (2)). |
| .PP |
| Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), |
| require the filesystem to be mounted with the |
| .B user_xattr |
| mount option in order for user extended attributes to be used. |
| .PP |
| In the current ext2, ext3, and ext4 filesystem implementations, |
| the total bytes used by the names and values of all of a file's |
| extended attributes must fit in a single filesystem block (1024, 2048 |
| or 4096 bytes, depending on the block size specified when the |
| filesystem was created). |
| .PP |
| In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no |
| practical limit on the number of extended attributes |
| associated with a file, and the algorithms used to store extended |
| attribute information on disk are scalable. |
| .PP |
| In the JFS, XFS, and Reiserfs filesystem implementations, |
| the limit on bytes used in an EA value is the ceiling imposed by the VFS. |
| .PP |
| In the Btrfs filesystem implementation, |
| the total bytes used for the name, value, and implementation overhead bytes |
| is limited to the filesystem |
| .I nodesize |
| value (16\ kB by default). |
| .SH CONFORMING TO |
| Extended attributes are not specified in POSIX.1, but some other systems |
| (e.g., the BSDs and Solaris) provide a similar feature. |
| .SH NOTES |
| Since the filesystems on which extended attributes are stored might also |
| be used on architectures with a different byte order and machine word |
| size, care should be taken to store attribute values in an |
| architecture-independent format. |
| .PP |
| This page was formerly named |
| .BR attr (5). |
| .\" .SH AUTHORS |
| .\" Andreas Gruenbacher, |
| .\" .RI < a.gruenbacher@bestbits.at > |
| .\" and the SGI XFS development team, |
| .\" .RI < linux-xfs@oss.sgi.com >. |
| .SH SEE ALSO |
| .BR attr (1), |
| .BR getfattr (1), |
| .BR setfattr (1), |
| .BR getxattr (2), |
| .BR ioctl_iflags (2), |
| .BR listxattr (2), |
| .BR removexattr (2), |
| .BR setxattr (2), |
| .BR acl (5), |
| .BR capabilities (7), |
| .BR selinux (8) |