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