+.\" Copyright (C) Andreas Gruenbacher, February 2001
+.\" Copyright (C) Silicon Graphics Inc, September 2001
.\"
-.\" Extended attributes system calls manual pages
-.\"
-.\" (C) Andreas Gruenbacher, February 2001
-.\" (C) Silicon Graphics Inc, September 2001
-.\"
+.\" %%%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
.\" 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, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
-.TH SETXATTR 2 "Extended Attributes" "Dec 2001" "Linux Programmer's Manual"
+.TH SETXATTR 2 2019-08-02 "Linux" "Linux Programmer's Manual"
.SH NAME
setxattr, lsetxattr, fsetxattr \- set an extended attribute value
.SH SYNOPSIS
.fam C
.nf
.B #include <sys/types.h>
-.B #include <attr/xattr.h>
-.sp
-.BI "int setxattr (const char\ *" path ", const char\ *" name ",
-.BI "\t\t\t const void\ *" value ", size_t " size ", int " flags );
-.BI "int lsetxattr (const char\ *" path ", const char\ *" name ",
-.BI "\t\t\t const void\ *" value ", size_t " size ", int " flags );
-.BI "int fsetxattr (int " filedes ", const char\ *" name ",
-.BI "\t\t\t const void\ *" value ", size_t " size ", int " flags );
+.B #include <sys/xattr.h>
+.PP
+.BI "int setxattr(const char\ *" path ", const char\ *" name ,
+.BI " const void\ *" value ", size_t " size ", int " flags );
+.BI "int lsetxattr(const char\ *" path ", const char\ *" name ,
+.BI " const void\ *" value ", size_t " size ", int " flags );
+.BI "int fsetxattr(int " fd ", const char\ *" name ,
+.BI " const void\ *" value ", size_t " size ", int " flags );
.fi
.fam T
.SH DESCRIPTION
Extended attributes are
.IR name :\c
.I value
-pairs associated with inodes (files, directories, symlinks, etc).
+pairs associated with inodes (files, directories, symbolic links, etc.).
They are extensions to the normal attributes which are associated
-with all inodes in the system (i.e. the
+with all inodes in the system (i.e., the
.BR stat (2)
data).
A complete overview of extended attributes concepts can be found in
-.BR attr (5).
+.BR xattr (7).
.PP
-.B setxattr
+.BR setxattr ()
sets the
.I value
of the extended attribute identified by
in the filesystem.
The
.I size
-of the
-.I value
-must be specified.
+argument specifies the size (in bytes) of
+.IR value ;
+a zero-length value is permitted.
.PP
-.B lsetxattr
-is identical to
-.BR setxattr ,
+.BR lsetxattr ()
+is identical to
+.BR setxattr (),
except in the case of a symbolic link, where the extended attribute is
set on the link itself, not the file that it refers to.
.PP
-.B fsetxattr
+.BR fsetxattr ()
is identical to
-.BR setxattr ,
-only the extended attribute is set on the open file pointed to by
-.I filedes
+.BR setxattr (),
+only the extended attribute is set on the open file referred to by
+.I fd
(as returned by
.BR open (2))
in place of
.IR path .
.PP
-An extended attribute name is a simple NULL-terminated string.
+An extended attribute name is a null-terminated string.
The
.I name
includes a namespace prefix; there may be several, disjoint
of an extended attribute is a chunk of arbitrary textual or
binary data of specified length.
.PP
-The
-.I flags
-parameter can be used to refine the semantics of the operation.
-XATTR_CREATE specifies a pure create, which fails if the named
-attribute exists already.
-XATTR_REPLACE specifies a pure replace operation, which fails if the
-named attribute does not already exist.
-By default (no flags), the extended attribute will be created if
-need be, or will simply replace the value if the attribute exists.
+By default
+(i.e.,
+.IR flags
+is zero),
+the extended attribute will be created if it does not exist,
+or the value will be replaced if the attribute already exists.
+To modify these semantics, one of the following values can be specified in
+.IR flags :
+.TP
+.B XATTR_CREATE
+Perform a pure create, which fails if the named attribute exists already.
+.TP
+.B XATTR_REPLACE
+Perform a pure replace operation,
+which fails if the named attribute does not already exist.
.SH RETURN VALUE
On success, zero is returned.
On failure, \-1 is returned and
.I errno
is set appropriately.
+.SH ERRORS
+.TP
+.B EDQUOT
+Disk quota limits meant that
+there is insufficient space remaining to store the extended attribute.
+.TP
+.B EEXIST
+.B XATTR_CREATE
+was specified, and the attribute exists already.
+.TP
+.B ENODATA
+.B XATTR_REPLACE
+was specified, and the attribute does not exist.
+.\" .RB ( ENOATTR
+.\" is defined to be a synonym for
+.\" .BR ENODATA
+.\" in
+.\" .IR <attr/attributes.h> .)
+.TP
+.B ENOSPC
+There is insufficient space remaining to store the extended attribute.
+.TP
+.B ENOTSUP
+The namespace prefix of
+.I name
+is not valid.
+.TP
+.B ENOTSUP
+Extended attributes are not supported by the filesystem, or are disabled,
+.TP
+.B EPERM
+The file is marked immutable or append-only.
+(See
+.BR ioctl_iflags (2).)
.PP
-If XATTR_CREATE is specified, and the attribute exists already,
-.I errno
-is set to EEXIST.
-If XATTR_REPLACE is specified, and the attribute does not exist,
-.I errno
-is set to ENOATTR.
-.PP
-If there is insufficient space remaining to store the extended attribute,
-.I errno
-is set to either ENOSPC, or EDQUOT if quota enforcement was the cause.
-.PP
-If extended attributes are not supported by the filesystem, or are disabled,
-.I errno
-is set to ENOTSUP.
-.PP
-The errors documented for the
+In addition, the errors documented in
.BR stat (2)
-system call are also applicable here.
-.SH AUTHORS
-Andreas Gruenbacher,
-.RI < a.gruenbacher@computer.org >
-and the SGI XFS development team,
-.RI < linux-xfs@oss.sgi.com >.
-Please send any bug reports or comments to these addresses.
+can also occur.
+.TP
+.B ERANGE
+The size of
+.I name
+or
+.I value
+exceeds a filesystem-specific limit.
+.SH VERSIONS
+These system calls have been available on Linux since kernel 2.4;
+glibc support is provided since version 2.3.
+.SH CONFORMING TO
+These system calls are Linux-specific.
+.\" .SH AUTHORS
+.\" Andreas Gruenbacher,
+.\" .RI < a.gruenbacher@computer.org >
+.\" and the SGI XFS development team,
+.\" .RI < linux-xfs@oss.sgi.com >.
+.\" Please send any bug reports or comments to these addresses.
.SH SEE ALSO
.BR getfattr (1),
.BR setfattr (1),
.BR open (2),
.BR removexattr (2),
.BR stat (2),
-.BR attr (5)
+.BR symlink (7),
+.BR xattr (7)
projects / thirdparty / man-pages.git / blobdiff