diff options
Diffstat (limited to 'man2/setxattr.2')
-rw-r--r-- | man2/setxattr.2 | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/man2/setxattr.2 b/man2/setxattr.2 new file mode 100644 index 000000000..d86dfefe5 --- /dev/null +++ b/man2/setxattr.2 @@ -0,0 +1,143 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.\" 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 +.\" the License, or (at your option) any later version. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" 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. +.\" +.TH SETXATTR 2 "Extended Attributes" "Dec 2001" "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 ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symlinks, 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 attr (5). +.PP +.B 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 +of the +.I value +must be specified. +.PP +.B 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 +is identical to +.BR setxattr , +only the extended attribute is set on the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a simple 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 +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. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.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 +.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. +.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 attr (5) |