1ATTR_MULTI(3)                XFS Compatibility API               ATTR_MULTI(3)
2
3
4

NAME

6       attr_multi,  attr_multif  -  manipulate  multiple  user attributes on a
7       filesystem object at once
8

C SYNOPSIS

10       #include <attr/attributes.h>
11
12       int attr_multi (const char *path, attr_multiop_t *oplist,
13                       int count, int flags);
14
15       int attr_multif (int fd, attr_multiop_t *oplist,
16                        int count, int flags);
17

DESCRIPTION

19       The attr_multi and attr_multif functions provide a way  to  operate  on
20       multiple attributes of a filesystem object at once.
21
22       Path  points  to  a path name for a filesystem object, and fd refers to
23       the file descriptor associated with a file.  The oplist is an array  of
24       attr_multiop_t structures.  Each element in that array describes a sin‐
25       gle attribute operation and provides all the  information  required  to
26       carry  out  that  operation and to check for success or failure of that
27       operation.  Count tells how many elements are in the oplist array.
28
29       The contents of an attr_multiop_t structure include the following  mem‐
30       bers:
31
32          int am_opcode; /* which operation to perform (see below) */
33          int am_error; /* [out arg] result of this sub-op (an errno) */
34          char *am_attrname; /* attribute name to work with */
35          char *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */
36          int am_length; /* [in/out arg] length of value */
37          int am_flags; /* flags (bit-wise OR of #defines below) */
38
39       The  am_opcode  field defines how the remaining fields are to be inter‐
40       preted and can take on one of the following values:
41
42          ATTR_OP_GET /* return the indicated attr's value */
43          ATTR_OP_SET /* set/create the indicated attr/value pair */
44          ATTR_OP_REMOVE /* remove the indicated attr */
45
46       The am_error field will contain the appropriate error  result  code  if
47       that  sub-operation  fails.  The result codes for a given sub-operation
48       are a subset of the result codes that are possible from the correspond‐
49       ing  single-attribute function call.  For example, the result code pos‐
50       sible from an ATTR_OP_GET sub-operation are a subset of those that  can
51       be returned from an attr_get function call.
52
53       The  am_attrname  field is a pointer to a NULL terminated string giving
54       the attribute name that the sub-operation should operate on.
55
56       The am_attrvalue, am_length and am_flags fields are used to  store  the
57       value of the named attribute, and some control flags for that sub-oper‐
58       ation, respectively.  Their use varies depending on the  value  of  the
59       am_opcode field.
60
61       ATTR_OP_GET
62              The  am_attrvalue field is a pointer to a empty buffer that will
63              be overwritten with the  value  of  the  named  attribute.   The
64              am_length field is initially the total size of the memory buffer
65              that the am_attrvalue field points to.  After the operation, the
66              am_length  field  contains  the  actual  size of the attribute´s
67              value.  The am_flags field may be set to the ATTR_ROOT flag.  If
68              the process has appropriate priviledges, the ROOT namespace will
69              be searched for the named attribute, otherwise the  USER  names‐
70              pace will be searched.
71
72       ATTR_OP_SET
73              The  am_attrvalue and am_length fields contain the new value for
74              the given attribute name and its length.  The ATTR_ROOT flag may
75              be  set  in  the am_flags field.  If the process has appropriate
76              priviledges, the ROOT namespace will be searched for  the  named
77              attribute,  otherwise  the USER namespace will be searched.  The
78              ATTR_CREATE and the ATTR_REPLACE flags may also be  set  in  the
79              am_flags  field  (but  not  simultaneously).  If the ATTR_CREATE
80              flag is set, the sub-operation will set the  am_error  field  to
81              EEXIST   if   the   named  attribute  already  exists.   If  the
82              ATTR_REPLACE  flag  is  set,  the  sub-operation  will  set  the
83              am_error  field  to  ENOATTR  if  the  named  attribute does not
84              already exist.  If neither of those two flags are  set  and  the
85              attribute  does  not  exist,  then the attribute will be created
86              with the given value.  If neither of those two flags are set and
87              the  attribute  already  exists, then the value will be replaced
88              with the given value.
89
90       ATTR_OP_REMOVE
91              The am_attrvalue and am_length  fields  are  not  used  and  are
92              ignored.   The  am_flags field may be set to the ATTR_ROOT flag.
93              If the process has appropriate priviledges, the  ROOT  namespace
94              will  be  searched  for  the named attribute, otherwise the USER
95              namespace will be searched.
96
97       The flags argument to the attr_multi call is used to control  following
98       of  symbolic links in the path argument.  The default is to follow sym‐
99       bolic links, flags should be set to ATTR_DONTFOLLOW to not follow  sym‐
100       bolic links.
101
102       attr_multi will fail if one or more of the following are true:
103
104       [ENOENT]         The named file does not exist.
105
106       [EPERM]          The  effective user ID does not match the owner of the
107                        file and the effective user ID is not super-user.
108
109       [ENOTDIR]        A component of the path prefix is not a directory.
110
111       [EACCES]         Search permission is denied on a component of the path
112                        prefix.
113
114       [EINVAL]         A  bit  other than ATTR_DONTFOLLOW was set in the flag
115                        argument.
116
117       [EFAULT]         Path, or oplist points outside the  allocated  address
118                        space of the process.
119
120       [ELOOP]          A path name lookup involved too many symbolic links.
121
122       [ENAMETOOLONG]   The length of path exceeds {MAXPATHLEN}, or a pathname
123                        component is longer than {MAXNAMELEN}.
124
125       attr_multif will fail if:
126
127       [EINVAL]       A bit was set in the flag argument, or fd  refers  to  a
128                      socket, not a file.
129
130       [EFAULT]       Oplist points outside the allocated address space of the
131                      process.
132
133       [EBADF]        Fd does not refer to a valid descriptor.
134

DIAGNOSTICS

136       On success, zero is returned.  On error, -1 is returned, and  errno  is
137       set  appropriately.   Note that the individual operations listed in the
138       oplist array each have their own error return fields.  The errno  vari‐
139       able  only  records  the  result of the attr_multi call itself, not the
140       result of any of the sub-operations.
141

SEE ALSO

143       attr(1), attr_get(3), attr_list(3), attr_remove(3), and attr_set(3).
144
145
146
147Dec 2001                      Extended Attributes                ATTR_MULTI(3)
Impressum