bsd/man/man2/setattrlist.2

   1 .\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   2 .\"
   3 .\" The contents of this file constitute Original Code as defined in and
   4 .\" are subject to the Apple Public Source License Version 1.1 (the
   5 .\" "License").  You may not use this file except in compliance with the
   6 .\" License.  Please obtain a copy of the License at
   7 .\" http://www.apple.com/publicsource and read it before using this file.
   8 .\"
   9 .\" This Original Code and all software distributed under the License are
  10 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  11 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  12 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  13 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  14 .\" License for the specific language governing rights and limitations
  15 .\" under the License.
  16 .\"
  17 .\"     @(#)setattrlist.2
  18 .
  19 .Dd December 15, 2003
  20 .Dt SETATTRLIST 2
  21 .Os Darwin
  22 .Sh NAME
  23 .Nm setattrlist ,
  24 .Nm fsetattrlist
  25 .Nd set file system attributes
  26 .Sh SYNOPSIS
  27 .Fd #include <sys/attr.h>
  28 .Fd #include <unistd.h>
  29 .Ft int
  30 .Fn setattrlist "const char* path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
  31 .Ft int
  32 .Fn fsetattrlist "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
  33 .
  34 .Sh DESCRIPTION
  35 The
  36 .Fn setattrlist
  37 and
  38 .Fn fsetattrlist
  39 functions set attributes (that is, metadata) of file system objects.
  40 They are the logical opposite of
  41 .Xr getattrlist 2 .
  42 The
  43 .Fn setattrlist
  44 function sets attributes about the file system object specified by
  45 .Fa path
  46 from the values in the buffer specified by
  47 .Fa attrBuf
  48 and
  49 .Fa attrBufSize ;
  50 the
  51 .Fn fsetattrlist
  52 function does the same for the
  53 .Fa fd
  54 file descriptor.
  55 The
  56 .Fa attrList
  57 parameter determines what attributes are set.
  58 The
  59 .Fa options
  60 parameter lets you control specific aspects of the function's behaviour.
  61 .Pp
  62 .
  63 The
  64 functions are only supported by certain volume format implementations.
  65 For maximum compatibility, client programs should use high-level APIs
  66 (such as the Carbon File Manager) to access file system attributes.
  67 These high-level APIs include logic to emulate file system attributes
  68 on volumes that don't support
  69 .Fn setattrlist
  70 and
  71 .Fn fsetattrlist .
  72 .Pp
  73 .
  74 .\" path parameter
  75 .
  76 The
  77 .Fa path
  78 parameter for
  79 .Fn setattrlist
  80 must reference a valid file system object.
  81 All directories listed in the path name leading to the object
  82 must be searchable.
  83 The
  84 .Fa fd
  85 parameter for
  86 .Fn fsetattrlist
  87 must be a valid file descriptor for the calling process.
  88 .
  89 The list of potentially settable attributes via
  90 .Fn setattrlist
  91 is different than the list of attributes that are accessible via
  92 .Fn getattrlist
  93 In particular, only the following attributes are modifiable via
  94 .Fn setattrlist
  95 and not all of them may be supported on all filesystems.
  96 .Pp
  97 .
  98 .Bl -item -compact
  99 .It
 100 ATTR_CMN_SCRIPT
 101 .It
 102 ATTR_CMN_CRTIME
 103 .It
 104 ATTR_CMN_MODTIME
 105 .It
 106 ATTR_CMN_CHGTIME
 107 .It
 108 ATTR_CMN_ACCTIME
 109 .It
 110 ATTR_CMN_BKUPTIME
 111 .It
 112 ATTR_CMN_FNDRINFO
 113 .It
 114 ATTR_CMN_OWNERID
 115 .It
 116 ATTR_CMN_GRPID
 117 .It
 118 ATTR_CMN_ACCESSMASK
 119 .It
 120 ATTR_CMN_FLAGS
 121 .It
 122 ATTR_CMN_EXTENDED_SECURITY
 123 .It
 124 ATTR_CMN_GRPUUID
 125 .Pp
 126 .It
 127 ATTR_VOL_NAME
 128 .It
 129 ATTR_VOL_INFO
 130 .Pp
 131 .It
 132 ATTR_FILE_DEVTYPE
 133 .El
 134 .Pp
 135 .
 136 .
 137 You must own the file system object in order to set any of the
 138 following attributes:
 139 .Pp
 140 .
 141 .Bl -item -compact
 142 .It
 143 ATTR_CMN_GRPID
 144 .It
 145 ATTR_CMN_ACCESSMASK
 146 .It
 147 ATTR_CMN_FLAGS
 148 .It
 149 ATTR_CMN_CRTIME
 150 .It
 151 ATTR_CMN_MODTIME
 152 .It
 153 ATTR_CMN_ACCTIME
 154 .Pp
 155 ATTR_CMN_CHGTIME
 156 .Fa cannot be set programmatically. Any attempt to set change time is ignored.
 157 .El
 158 .Pp
 159 .
 160 You must be root (that is, your process's effective UID must be 0) in order to change the
 161 .Dv ATTR_CMN_OWNERID
 162 attribute
 163 Setting other attributes requires that you have write access to the object.
 164 .Pp
 165 .
 166 .\" attrList parameter
 167 .
 168 The
 169 .Fa attrList
 170 parameter is a pointer to an
 171 .Vt attrlist
 172 structure.
 173 You are responsible for filling out all fields of this structure before calling the function.
 174 See the discussion of the
 175 .Xr getattrlist 2
 176 function for a detailed description of this structure.
 177 To set an attribute you must set the corresponding bit in the appropriate
 178 .Vt attrgroup_t
 179 field of the
 180 .Vt attrlist
 181 structure.
 182 .Pp
 183 .
 184 .\" attrBuf and attrBufSize parameters
 185 .
 186 The
 187 .Fa attrBuf
 188 and
 189 .Fa attrBufSize
 190 parameters specify a buffer that contains the attribute values to set.
 191 Attributes are packed in exactly the same way as they are returned from
 192 .Xr getattrlist 2
 193 except that, when setting attributes, the buffer does not include the leading
 194 .Vt u_int32_t
 195 length value.
 196 .Pp
 197 .
 198 .\" option parameter
 199 .
 200 The
 201 .Fa options
 202 parameter is a bit set that controls the behaviour of
 203 .Fn setattrlist .
 204 The following option bits are defined.
 205 .
 206 .Bl -tag -width XXXbitmapcount
 207 .
 208 .It FSOPT_NOFOLLOW
 209 If this bit is set,
 210 .Fn setattrlist
 211 will not follow a symlink if it occurs as
 212 the last component of
 213 .Fa path .
 214 .
 215 .El
 216 .
 217 .Sh RETURN VALUES
 218 Upon successful completion a value of 0 is returned.
 219 Otherwise, a value of -1 is returned and
 220 .Va errno
 221 is set to indicate the error.
 222 .
 223 .Sh COMPATIBILITY
 224 Not all volumes support
 225 .Fn setattrlist .
 226 However, if a volume supports
 227 .Xr getattrlist 2 ,
 228 it must also support
 229 .Fn setattrlist .
 230 See the documentation for
 231 .Xr getattrlist 2
 232 for details on how to tell whether a volume supports it.
 233 .Pp
 234 .
 235 The
 236 .Fn setattrlist
 237 function has been undocumented for more than two years.
 238 In that time a number of volume format implementations have been created without
 239 a proper specification for the behaviour of this routine.
 240 You may encounter volume format implementations with slightly different
 241 behaviour than what is described here.
 242 Your program is expected to be tolerant of this variant behaviour.
 243 .Pp
 244 .
 245 If you're implementing a volume format that supports
 246 .Fn setattrlist ,
 247 you should be careful to support the behaviour specified by this document.
 248 .
 249 .Sh ERRORS
 250 .Fn setattrlist
 251 and
 252 .Fn fsetattrlist
 253 will fail if:
 254 .Bl -tag -width Er
 255 .
 256 .It Bq Er ENOTSUP
 257 The call is not supported by the volume.
 258 .
 259 .It Bq Er ENOTDIR
 260 A component of the path for
 261 .Fn setattrlist
 262 prefix is not a directory.
 263 .
 264 .It Bq Er ENAMETOOLONG
 265 A component of a path name for
 266 .Fn setattrlist
 267 exceeded
 268 .Dv NAME_MAX
 269 characters, or an entire path name exceeded
 270 .Dv PATH_MAX
 271 characters.
 272 .
 273 .It Bq Er ENOENT
 274 The file system object for
 275 .Fn setattrlist
 276 does not exist.
 277 .
 278 .It Bq Er EBADF
 279 The file descriptor argument for
 280 .Fn fsetattrlist
 281 is not a valid file descriptor.
 282 .
 283 .It Bq Er EROFS
 284 The volume is read-only.
 285 .
 286 .It Bq Er EACCES
 287 Search permission is denied for a component of the path prefix for
 288 .Fn setattrlist .
 289 .
 290 .It Bq Er ELOOP
 291 Too many symbolic links were encountered in translating the pathname for
 292 .Fn setattrlist .
 293 .
 294 .It Bq Er EFAULT
 295 .Fa path ,
 296 .Fa attrList
 297 or
 298 .Em attrBuf
 299 points to an invalid address.
 300 .
 301 .It Bq Er EINVAL
 302 The
 303 .Fa bitmapcount
 304 field of
 305 .Fa attrList
 306 is not
 307 .Dv ATTR_BIT_MAP_COUNT .
 308 .
 309 .It Bq Er EINVAL
 310 You try to set an invalid attribute.
 311 .
 312 .It Bq Er EINVAL
 313 You try to set an attribute that is read-only.
 314 .
 315 .It Bq Er EINVAL
 316 You try to set volume attributes and directory or file attributes at the same time.
 317 .
 318 .It Bq Er EINVAL
 319 You try to set volume attributes but
 320 .Fa path
 321 does not reference the root of the volume.
 322 .
 323 .It Bq Er EPERM
 324 You try to set an attribute that can only be set by the owner.
 325 .
 326 .It Bq Er EACCES
 327 You try to set an attribute that's only settable if you have write permission,
 328 and you do not have write permission.
 329 .
 330 .It Bq Er EINVAL
 331 The buffer size you specified in
 332 .Fa attrBufSize
 333 is too small to hold all the attributes that you are trying to set.
 334 .
 335 .It Bq Er EIO
 336 An I/O error occurred while reading from or writing to the file system.
 337 .El
 338 .Pp
 339 .
 340 .Sh CAVEATS
 341 .
 342 If you try to set any volume attributes, you must set
 343 .Dv ATTR_VOL_INFO
 344 in the
 345 .Fa volattr
 346 field, even though it consumes no data from the attribute buffer.
 347 .Pp
 348 .
 349 For more caveats, see also the compatibility notes above.
 350 .
 351 .Sh EXAMPLES
 352 .
 353 The following code shows how to set the file type and creator of
 354 a file by getting the
 355 .Dv ATTR_CMN_FNDRINFO
 356 attribute using
 357 .Xr getattrlist 2 ,
 358 modifying the appropriate fields of the 32-byte Finder information structure,
 359 and then setting the attribute back using
 360 .Fn setattrlist .
 361 This assumes that the target volume supports the required attributes
 362 .
 363 .Bd -literal
 364 #include <assert.h>
 365 #include <stdio.h>
 366 #include <stddef.h>
 367 #include <string.h>
 368 #include <sys/attr.h>
 369 #include <sys/errno.h>
 370 #include <unistd.h>
 371 #include <sys/vnode.h>
 372 .Pp
 373 .
 374 typedef struct attrlist attrlist_t;
 375 .Pp
 376 .
 377 struct FInfoAttrBuf {
 378     u_int32_t       length;
 379     fsobj_type_t    objType;
 380     char            finderInfo[32];
 381 };
 382 typedef struct FInfoAttrBuf FInfoAttrBuf;
 383 .Pp
 384 .
 385 static int FInfoDemo(
 386     const char *path,
 387     const char *type,
 388     const char *creator
 389 )
 390 {
 391     int             err;
 392     attrlist_t      attrList;
 393     FInfoAttrBuf    attrBuf;
 394 .Pp
 395
 396     assert( strlen(type)    == 4 );
 397     assert( strlen(creator) == 4 );
 398 .Pp
 399 .
 400     memset(&attrList, 0, sizeof(attrList));
 401     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 402     attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
 403 .Pp
 404
 405     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
 406     if (err != 0) {
 407         err = errno;
 408     }
 409 .Pp
 410
 411     if ( (err == 0) && (attrBuf.objType != VREG) ) {
 412         fprintf(stderr, "Not a standard file.\en");
 413         err = EINVAL;
 414     } else {
 415         memcpy( &attrBuf.finderInfo[0], type,    4 );
 416         memcpy( &attrBuf.finderInfo[4], creator, 4 );
 417
 418         attrList.commonattr = ATTR_CMN_FNDRINFO;
 419         err = setattrlist(
 420             path,
 421             &attrList,
 422             attrBuf.finderInfo,
 423             sizeof(attrBuf.finderInfo),
 424             0
 425         );
 426     }
 427 .Pp
 428     return err;
 429 }
 430 .Ed
 431 .Pp
 432 .
 433 .Sh SEE ALSO
 434 .
 435 .Xr chflags 2 ,
 436 .Xr chmod 2 ,
 437 .Xr chown 2 ,
 438 .Xr getattrlist 2 ,
 439 .Xr getdirentriesattr 2 ,
 440 .Xr searchfs 2 ,
 441 .Xr utimes 2
 442 .
 443 .Sh HISTORY
 444 A
 445 .Fn setattrlist
 446 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 447 .