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