summaryrefslogtreecommitdiffstats
path: root/man2/setxattr.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/setxattr.2159
1 files changed, 159 insertions, 0 deletions
diff --git a/man2/setxattr.2 b/man2/setxattr.2
new file mode 100644
index 0000000..cc2a6b0
--- /dev/null
+++ b/man2/setxattr.2
@@ -0,0 +1,159 @@
+.\" Copyright (C) Andreas Gruenbacher, February 2001
+.\" Copyright (C) Silicon Graphics Inc, September 2001
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH setxattr 2 2023-07-28 "Linux man-pages 6.05.01"
+.SH NAME
+setxattr, lsetxattr, fsetxattr \- set an extended attribute value
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/xattr.h>
+.PP
+.BI "int setxattr(const char *" path ", const char *" name ,
+.BI " const void " value [. size "], size_t " size ", int " flags );
+.BI "int lsetxattr(const char *" path ", const char *" name ,
+.BI " const void " value [. size "], size_t " size ", int " flags );
+.BI "int fsetxattr(int " fd ", const char *" name ,
+.BI " const void " value [. size "], size_t " size ", int " flags );
+.fi
+.SH DESCRIPTION
+Extended attributes are
+.IR name : value
+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
+.BR stat (2)
+data).
+A complete overview of extended attributes concepts can be found in
+.BR xattr (7).
+.PP
+.BR setxattr ()
+sets the
+.I value
+of the extended attribute identified by
+.I name
+and associated with the given
+.I path
+in the filesystem.
+The
+.I size
+argument specifies the size (in bytes) of
+.IR value ;
+a zero-length value is permitted.
+.PP
+.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
+.BR fsetxattr ()
+is identical to
+.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 null-terminated string.
+The
+.I name
+includes a namespace prefix; there may be several, disjoint
+namespaces associated with an individual inode.
+The
+.I value
+of an extended attribute is a chunk of arbitrary textual or
+binary data of specified length.
+.PP
+By default
+(i.e.,
+.I 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 to indicate the error.
+.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
+In addition, the errors documented in
+.BR stat (2)
+can also occur.
+.TP
+.B ERANGE
+The size of
+.I name
+or
+.I value
+exceeds a filesystem-specific limit.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.4,
+glibc 2.3.
+.\" .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 getxattr (2),
+.BR listxattr (2),
+.BR open (2),
+.BR removexattr (2),
+.BR stat (2),
+.BR symlink (7),
+.BR xattr (7)