man2/setxattr.2

   1 .\" Copyright (C) Andreas Gruenbacher, February 2001
   2 .\" Copyright (C) Silicon Graphics Inc, September 2001
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH setxattr 2 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 setxattr, lsetxattr, fsetxattr \- set an extended attribute value
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <sys/xattr.h>
  15 .P
  16 .BI "int setxattr(const char *" path ", const char *" name ,
  17 .BI "              const void " value [. size "], size_t " size ", int " flags );
  18 .BI "int lsetxattr(const char *" path ", const char *" name ,
  19 .BI "              const void " value [. size "], size_t " size ", int " flags );
  20 .BI "int fsetxattr(int " fd ", const char *" name ,
  21 .BI "              const void " value [. size "], size_t " size ", int " flags );
  22 .fi
  23 .SH DESCRIPTION
  24 Extended attributes are
  25 .IR name : value
  26 pairs associated with inodes (files, directories, symbolic links, etc.).
  27 They are extensions to the normal attributes which are associated
  28 with all inodes in the system (i.e., the
  29 .BR stat (2)
  30 data).
  31 A complete overview of extended attributes concepts can be found in
  32 .BR xattr (7).
  33 .P
  34 .BR setxattr ()
  35 sets the
  36 .I value
  37 of the extended attribute identified by
  38 .I name
  39 and associated with the given
  40 .I path
  41 in the filesystem.
  42 The
  43 .I size
  44 argument specifies the size (in bytes) of
  45 .IR value ;
  46 a zero-length value is permitted.
  47 .P
  48 .BR lsetxattr ()
  49 is identical to
  50 .BR setxattr (),
  51 except in the case of a symbolic link, where the extended attribute is
  52 set on the link itself, not the file that it refers to.
  53 .P
  54 .BR fsetxattr ()
  55 is identical to
  56 .BR setxattr (),
  57 only the extended attribute is set on the open file referred to by
  58 .I fd
  59 (as returned by
  60 .BR open (2))
  61 in place of
  62 .IR path .
  63 .P
  64 An extended attribute name is a null-terminated string.
  65 The
  66 .I name
  67 includes a namespace prefix; there may be several, disjoint
  68 namespaces associated with an individual inode.
  69 The
  70 .I value
  71 of an extended attribute is a chunk of arbitrary textual or
  72 binary data of specified length.
  73 .P
  74 By default
  75 (i.e.,
  76 .I flags
  77 is zero),
  78 the extended attribute will be created if it does not exist,
  79 or the value will be replaced if the attribute already exists.
  80 To modify these semantics, one of the following values can be specified in
  81 .IR flags :
  82 .TP
  83 .B XATTR_CREATE
  84 Perform a pure create, which fails if the named attribute exists already.
  85 .TP
  86 .B XATTR_REPLACE
  87 Perform a pure replace operation,
  88 which fails if the named attribute does not already exist.
  89 .SH RETURN VALUE
  90 On success, zero is returned.
  91 On failure, \-1 is returned and
  92 .I errno
  93 is set to indicate the error.
  94 .SH ERRORS
  95 .TP
  96 .B EDQUOT
  97 Disk quota limits meant that
  98 there is insufficient space remaining to store the extended attribute.
  99 .TP
 100 .B EEXIST
 101 .B XATTR_CREATE
 102 was specified, and the attribute exists already.
 103 .TP
 104 .B ENODATA
 105 .B XATTR_REPLACE
 106 was specified, and the attribute does not exist.
 107 .\" .RB ( ENOATTR
 108 .\" is defined to be a synonym for
 109 .\" .BR ENODATA
 110 .\" in
 111 .\" .IR <attr/attributes.h> .)
 112 .TP
 113 .B ENOSPC
 114 There is insufficient space remaining to store the extended attribute.
 115 .TP
 116 .B ENOTSUP
 117 The namespace prefix of
 118 .I name
 119 is not valid.
 120 .TP
 121 .B ENOTSUP
 122 Extended attributes are not supported by the filesystem, or are disabled,
 123 .TP
 124 .B EPERM
 125 The file is marked immutable or append-only.
 126 (See
 127 .BR ioctl_iflags (2).)
 128 .P
 129 In addition, the errors documented in
 130 .BR stat (2)
 131 can also occur.
 132 .TP
 133 .B ERANGE
 134 The size of
 135 .I name
 136 or
 137 .I value
 138 exceeds a filesystem-specific limit.
 139 .SH STANDARDS
 140 Linux.
 141 .SH HISTORY
 142 Linux 2.4,
 143 glibc 2.3.
 144 .\" .SH AUTHORS
 145 .\" Andreas Gruenbacher,
 146 .\" .RI < a.gruenbacher@computer.org >
 147 .\" and the SGI XFS development team,
 148 .\" .RI < linux-xfs@oss.sgi.com >.
 149 .\" Please send any bug reports or comments to these addresses.
 150 .SH SEE ALSO
 151 .BR getfattr (1),
 152 .BR setfattr (1),
 153 .BR getxattr (2),
 154 .BR listxattr (2),
 155 .BR open (2),
 156 .BR removexattr (2),
 157 .BR stat (2),
 158 .BR symlink (7),
 159 .BR xattr (7)