.\"
.\" Extended attributes manual page
.\"
.\" (C) Andreas Gruenbacher, 2000
.\" (C) Silicon Graphics Inc, 2001
.\"
.TH ATTR 5
.SH NAME
attr - 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 \- for 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 retrieve a list of
attribute names defined for that file or directory.
.PP
Extended attributes are accessed as atomic objects.
Reading retrieves the whole value of an attribute and stores it in a buffer.
Writing replaces any previous value with the new value.
.PP
Space consumed for extended attributes is counted towards the disk quotas
of the file owner and file group.
.PP
Currently, support for extended attributes is implemented on Linux by
the ext2, ext3 and XFS filesystem patches, which can be downloaded from
.B http://acl.bestbits.at/
and
.B http://oss.sgi.com/projects/xfs/
respectively.
.SH EXTENDED ATTRIBUTE NAMESPACES
Attribute names are zero-terminated strings.
The attribute name is always specified in the fully qualified
.IR namespace.attribute
form, eg.
.I user.mime_type
or
.IR system.posix_acl_access .
.PP
The namespace mechanism is used to define different classes of extended
attributes.
These different classes exist for several reasons, e.g. the permissions
and capabilities required for manipulating extended attributes of one
namespace may differ to another.
.PP
Currently the
.I user
and
.I system
extended attribute classes are defined as described below. Additional
classes, such as attributes that are
accessible only to processes trusted by the kernel, may be added in the
future.
.SS Extended user attributes
Extended user 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.
.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 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, extended user attributes
are disallowed for special files, and access to extended user
attributes is restricted to the owner or users with appropriate
capabilities for directories with the sticky bit set (see the
.BR chmod (1)
manual page for an explanation of Sticky Directories).
.SS Extended system attributes
Extended system attributes are used by the kernel to store system
objects such as Access Control Lists and Capabilities.  Read and write
access permissions to system attributes depend on the policy implemented
for each system attribute implemented in the kernel.
.SH 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.
.PP
In the current ext2 and ext3 filesystem implementations, all extended
attributes must fit on a single filesystem block (1024, 2048 or 4096 bytes,
depending on the block size specified when the filesystem
was created). This limit may be removed in a future version.
.PP
In the XFS filesystem implementation, 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 (stored
either inline in the inode, as an extent, or in a B+ tree).
.SH ADDITIONAL 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.
.SH AUTHORS
Andreas Gruenbacher,
.RI < a.gruenbacher@computer.org >
and the SGI XFS development team,
.RI < linux-xfs@oss.sgi.com >.
.SH SEE ALSO
getfattr(1),
setfattr(1).