.\"
.\" 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
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 and typically have a short
(filesystem dependent) length.
The attribute name is always specified in the full
.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.
They have also been used to distinguish filesystem-specific attribute
names from canonical, filesystem-independent attribute names.
.PP
The extended attribute namespace is always specified as the first
component of the name.
This greatly simplifies certain operations, and provides a consistent,
explicit interface for all operations.
.PP
Extended
.I 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.
User attributes are subject to the same permissions as the contents of a file.
The file owner can decide who is allowed to read and/or set these attributes.
.PP
Extended
.I 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.
.PP
Additional types of extended attributes with different access permissions,
such as attributes that are accessible only to processes trusted by the
kernel, may be added in the future.
.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.
Device special files cannot be associated with extended user attributes
(but they may be associated with extended system attributes). Permissions
of device special files define access to the devices rather than to the
device special files.
.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).
XFS allows extended attributes to be associated with device inodes.
.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).