1 files changed, 180 insertions, 0 deletions
diff --git a/man/man7/xattr.7 b/man/man7/xattr.7
new file mode 100644
index 000000000..540179564
--- /dev/null
+++ b/man/man7/xattr.7
@@ -0,0 +1,180 @@
+.\" 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.
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH xattr 7 (date) "Linux man-pages (unreleased)"
+.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.
+.P
+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\[em]for example, additional security features such as
+Access Control Lists (ACLs) may be implemented using extended attributes.
+.P
+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.
+.P
+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.
+.P
+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
+.I namespace.attribute
+form, for example,
+.IR user.mime_type ,
+.IR trusted.md5sum ,
+.IR system.posix_acl_access ,
+or
+.IR security.selinux .
+.P
+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.
+.P
+Currently, the
+.IR security ,
+.IR system ,
+.IR trusted ,
+and
+.I 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.
+.P
+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.
+.P
+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-imposed limits on attribute names and values are 255 bytes
+and 64\ kB, respectively.
+The list of attribute names that
+can be returned is also limited to 64\ kB
+(see BUGS in
+.BR listxattr (2)).
+.P
+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.
+.P
+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).
+.P
+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.
+.P
+In the JFS, XFS, and Reiserfs filesystem implementations,
+the limit on bytes used in an EA value is the ceiling imposed by the VFS.
+.P
+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 STANDARDS
+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.
+.P
+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)