man/man3/attr_multi.3

   1 .\" Copyright (C) 2001, 2002, 2003, 2006 Silicon Graphics, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual.  If not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\"
  23 .TH ATTR_MULTI 3 "Extended Attributes" "Dec 2001" "XFS Compatibility API"
  24 .SH NAME
  25 attr_multi, attr_multif \- manipulate multiple user attributes on a filesystem object at once
  26 .SH C SYNOPSIS
  27 .PP
  28 .sp
  29 .nf
  30 .B #include <attr/attributes.h>
  31 .sp
  32 .B "int attr_multi (const char *\f2path\f3, attr_multiop_t *\f2oplist\f3, "
  33 .B "                int \f2count\f3, int \f2flags\f3);"
  34 .PP
  35 .B "int attr_multif (int \f2fd\f3, attr_multiop_t *\f2oplist\f3, "
  36 .B "                 int \f2count\f3, int \f2flags\f3);"
  37 .Op
  38 .SH DESCRIPTION
  39 The
  40 .B attr_multi
  41 and
  42 .B attr_multif
  43 functions provide a way to operate on multiple attributes of a
  44 filesystem object at once.
  45 .P
  46 .I Path
  47 points to a path name for a filesystem object, and
  48 .I fd
  49 refers to the file descriptor associated with a file.
  50 The
  51 .I oplist
  52 is an array of \f4attr_multiop_t\fP structures.
  53 Each element in that array describes a single attribute operation
  54 and provides all the information required to carry out that operation
  55 and to check for success or failure of that operation.
  56 .I Count
  57 tells how many elements are in the
  58 .I oplist
  59 array.
  60 .PP
  61 .Op c p a
  62 The contents of an \f4attr_multiop_t\fP structure include
  63 the following members:
  64 .P
  65 .RS 3
  66 .nf
  67 .ft 4
  68 .ta 9n 22n
  69 int am_opcode; /* which operation to perform (see below) */
  70 int am_error; /* [out arg] result of this sub-op (an errno) */
  71 char *am_attrname; /* attribute name to work with */
  72 char *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */
  73 int am_length; /* [in/out arg] length of value */
  74 int am_flags; /* flags (bit-wise OR of #defines below) */
  75 .ft 1
  76 .fi
  77 .RE
  78 .PP
  79 The
  80 .I am_opcode
  81 field defines how the remaining fields are to be interpreted
  82 and can take on one of the following values:
  83 .P
  84 .RS 3
  85 .nf
  86 .ft 4
  87 .ta 9n 22n
  88 ATTR_OP_GET /* return the indicated attr's value */
  89 ATTR_OP_SET /* set/create the indicated attr/value pair */
  90 ATTR_OP_REMOVE /* remove the indicated attr */
  91 .ft 1
  92 .fi
  93 .RE
  94 .PP
  95 The
  96 .I am_error
  97 field will contain the appropriate error result code
  98 if that sub-operation fails.
  99 The result codes for a given sub-operation are a subset of
 100 the result codes that are possible from the corresponding
 101 single-attribute function call.
 102 For example, the result code possible from an \f4ATTR_OP_GET\fP
 103 sub-operation are a subset of those that can be returned from an
 104 .B attr_get
 105 function call.
 106 .PP
 107 The
 108 .I am_attrname
 109 field is a pointer to a NULL terminated string giving the attribute name
 110 that the sub-operation should operate on.
 111 .PP
 112 The
 113 .I am_attrvalue,
 114 .I am_length
 115 and
 116 .I am_flags
 117 fields are used to store the value of the named attribute,
 118 and some control flags for that sub-operation, respectively.
 119 Their use varies depending on the value of the
 120 .I am_opcode
 121 field.
 122 .TP
 123 .SM
 124 .B \%ATTR_OP_GET
 125 The
 126 .I am_attrvalue
 127 field is a pointer to a empty buffer that will be overwritten
 128 with the value of the named attribute.
 129 The
 130 .I am_length
 131 field is initially the total size of the memory buffer that the
 132 .I am_attrvalue
 133 field points to.
 134 After the operation, the
 135 .I am_length
 136 field contains the actual size of the attribute\'s value.
 137 The
 138 .I am_flags
 139 field may be set to the \f4ATTR_ROOT\fP flag.
 140 If the process has appropriate priviledges,
 141 the ROOT namespace will be searched for the named attribute,
 142 otherwise the USER namespace will be searched.
 143 .TP
 144 .SM
 145 .B \%ATTR_OP_SET
 146 The
 147 .I am_attrvalue
 148 and
 149 .I am_length
 150 fields contain the new value for the given attribute name and its length.
 151 The \f4ATTR_ROOT\fP flag may be set in the
 152 .I am_flags
 153 field.
 154 If the process has appropriate priviledges,
 155 the ROOT namespace will be searched for the named attribute,
 156 otherwise the USER namespace will be searched.
 157 The \f4ATTR_CREATE\fP and the \f4ATTR_REPLACE\fP flags
 158 may also be set in the
 159 .I am_flags
 160 field (but not simultaneously).
 161 If the \f4ATTR_CREATE\fP flag is set,
 162 the sub-operation will set the
 163 .I am_error
 164 field to EEXIST if the named attribute already exists.
 165 If the \f4ATTR_REPLACE\fP flag is set,
 166 the sub-operation will set the
 167 .I am_error
 168 field to ENOATTR if the named attribute does not already exist.
 169 If neither of those two flags are set and the attribute does not exist,
 170 then the attribute will be created with the given value.
 171 If neither of those two flags are set and the attribute already exists,
 172 then the value will be replaced with the given value.
 173 .TP
 174 .SM
 175 .B \%ATTR_OP_REMOVE
 176 The
 177 .I am_attrvalue
 178 and
 179 .I am_length
 180 fields are not used and are ignored.
 181 The
 182 .I am_flags
 183 field may be set to the \f4ATTR_ROOT\fP flag.
 184 If the process has appropriate priviledges,
 185 the ROOT namespace will be searched for the named attribute,
 186 otherwise the USER namespace will be searched.
 187 .PP
 188 The
 189 .I flags
 190 argument to the
 191 .B attr_multi
 192 call is used to control following of symbolic links in the
 193 .I path
 194 argument.
 195 The default is to follow symbolic links,
 196 .I flags
 197 should be set to ATTR_DONTFOLLOW to not follow symbolic links.
 198 .PP
 199 .B attr_multi
 200 will fail if one or more of the following are true:
 201 .TP 17
 202 .SM
 203 \%[ENOENT]
 204 The named file does not exist.
 205 .TP
 206 .SM
 207 \%[EPERM]
 208 The effective user
 209 .SM ID
 210 does not match the owner of the file
 211 and the effective user
 212 .SM ID
 213 is not super-user.
 214 .TP
 215 .SM
 216 \%[ENOTDIR]
 217 A component of the
 218 path prefix
 219 is not a directory.
 220 .TP
 221 .SM
 222 \%[EACCES]
 223 Search permission is denied on a
 224 component of the
 225 path prefix.
 226 .TP
 227 .SM
 228 \%[EINVAL]
 229 A bit other than ATTR_DONTFOLLOW was set in the
 230 .I flag
 231 argument.
 232 .TP
 233 .SM
 234 \%[EFAULT]
 235 .I Path,
 236 or
 237 .I oplist
 238 points outside the allocated address space of the process.
 239 .TP
 240 .SM
 241 \%[ELOOP]
 242 A path name lookup involved too many symbolic links.
 243 .TP
 244 .SM
 245 \%[ENAMETOOLONG]
 246 The length of
 247 .I path
 248 exceeds
 249 .SM
 250 .RI { MAXPATHLEN },
 251 or a pathname component is longer than
 252 .SM
 253 .RI { MAXNAMELEN }.
 254 .PP
 255 .B attr_multif
 256 will fail if:
 257 .TP 15
 258 .SM
 259 \%[EINVAL]
 260 A bit was set in the
 261 .I flag
 262 argument, or
 263 .I fd\^
 264 refers to a socket, not a file.
 265 .TP
 266 .SM
 267 \%[EFAULT]
 268 .I Oplist
 269 points outside the allocated address space of the process.
 270 .TP
 271 .SM
 272 \%[EBADF]
 273 .I Fd\^
 274 does not refer to a valid descriptor.
 275 .SH "DIAGNOSTICS"
 276 On success, zero is returned.  On error, \-1 is returned, and
 277 .I errno
 278 is set appropriately.
 279 Note that the individual operations listed in the
 280 .I oplist
 281 array each have their own error return fields.
 282 The
 283 .I errno
 284 variable only records the result of the
 285 .I attr_multi
 286 call itself, not the result of any of the sub-operations.
 287 .SH "SEE ALSO"
 288 .BR attr (1),
 289 .BR attr_get (3),
 290 .BR attr_list (3),
 291 .BR attr_remove (3),
 292 and
 293 .BR attr_set (3).