+.\" 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 2001-12-31 "Linux" "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
+.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 ,
.BR stat (2)
data).
A complete overview of extended attributes concepts can be found in
-.BR attr (5).
+.BR xattr (7).
.PP
.BR setxattr ()
sets the
.I name
and associated with the given
.I path
-in the file system.
+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
.BR lsetxattr ()
is identical to
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.
+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
-specifies a pure create, which fails if the named
-attribute exists already.
+Perform a pure create, which fails if the named attribute exists already.
+.TP
.B 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.
+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.
-.PP
-If
+.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
-is specified, and the attribute exists already,
-.I errno
-is set to
-.BR EEXIST .
-If
+was specified, and the attribute exists already.
+.TP
+.B ENODATA
.B XATTR_REPLACE
-is specified, and the attribute does not exist,
-.I errno
-is set to
-.BR ENOATTR .
-.PP
-If there is insufficient space remaining to store the extended attribute,
-.I errno
-is set to either
-.BR ENOSPC ,
-or
-.B EDQUOT
-if quota enforcement was the cause.
-.PP
-If extended attributes are not supported by the file system, or are disabled,
-.I errno
-is set to
-.BR ENOTSUP .
+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
-The errors documented for the
+In addition, the errors documented in
.BR stat (2)
-system call are also applicable here.
+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"
+.SH CONFORMING TO
These system calls are Linux-specific.
.\" .SH AUTHORS
.\" Andreas Gruenbacher,
.BR open (2),
.BR removexattr (2),
.BR stat (2),
-.BR attr (5)
+.BR symlink (7),
+.BR xattr (7)
projects / thirdparty / man-pages.git / blobdiff