setxattr(2)

1setxattr(2)                   System Calls Manual                  setxattr(2)
2
3
4

NAME

6       setxattr, lsetxattr, fsetxattr - set an extended attribute value
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/xattr.h>
13
14       int setxattr(const char *path, const char *name,
15                     const void value[.size], size_t size, int flags);
16       int lsetxattr(const char *path, const char *name,
17                     const void value[.size], size_t size, int flags);
18       int fsetxattr(int fd, const char *name,
19                     const void value[.size], size_t size, int flags);
20

DESCRIPTION

22       Extended attributes are name:value pairs associated with inodes (files,
23       directories, symbolic links, etc.).  They are extensions to the  normal
24       attributes  which  are  associated with all inodes in the system (i.e.,
25       the stat(2) data).  A complete overview of extended attributes concepts
26       can be found in xattr(7).
27
28       setxattr()  sets the value of the extended attribute identified by name
29       and associated with the given path in the filesystem.  The  size  argu‐
30       ment  specifies  the  size  (in bytes) of value; a zero-length value is
31       permitted.
32
33       lsetxattr() is identical to setxattr(), except in the case  of  a  sym‐
34       bolic link, where the extended attribute is set on the link itself, not
35       the file that it refers to.
36
37       fsetxattr() is identical to setxattr(), only the extended attribute  is
38       set  on  the  open  file  referred to by fd (as returned by open(2)) in
39       place of path.
40
41       An extended attribute name is a null-terminated string.  The  name  in‐
42       cludes  a  namespace  prefix; there may be several, disjoint namespaces
43       associated with an individual inode.  The value of an  extended  attri‐
44       bute  is  a  chunk  of  arbitrary  textual  or binary data of specified
45       length.
46
47       By default (i.e., flags is zero), the extended attribute will  be  cre‐
48       ated  if it does not exist, or the value will be replaced if the attri‐
49       bute already exists.  To modify these semantics, one of  the  following
50       values can be specified in flags:
51
52       XATTR_CREATE
53              Perform a pure create, which fails if the named attribute exists
54              already.
55
56       XATTR_REPLACE
57              Perform a pure replace operation, which fails if the  named  at‐
58              tribute does not already exist.
59

RETURN VALUE

61       On  success, zero is returned.  On failure, -1 is returned and errno is
62       set to indicate the error.
63

ERRORS

65       EDQUOT Disk quota limits meant that there is insufficient space remain‐
66              ing to store the extended attribute.
67
68       EEXIST XATTR_CREATE was specified, and the attribute exists already.
69
70       ENODATA
71              XATTR_REPLACE was specified, and the attribute does not exist.
72
73       ENOSPC There  is insufficient space remaining to store the extended at‐
74              tribute.
75
76       ENOTSUP
77              The namespace prefix of name is not valid.
78
79       ENOTSUP
80              Extended attributes are not supported by the filesystem, or  are
81              disabled,
82
83       EPERM  The   file   is   marked   immutable   or   append-only.    (See
84              ioctl_iflags(2).)
85
86       In addition, the errors documented in stat(2) can also occur.
87
88       ERANGE The size of name or value exceeds a filesystem-specific limit.
89

STANDARDS

91       Linux.
92

HISTORY

94       Linux 2.4, glibc 2.3.
95