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 You must own the file system object in order to set any of the
  89 following attributes:
  90 .Pp
  91 .
  92 .Bl -item -compact
  93 .It
  94 ATTR_CMN_GRPID
  95 .It
  96 ATTR_CMN_ACCESSMASK
  97 .It
  98 ATTR_CMN_FLAGS
  99 .It
 100 ATTR_CMN_CRTIME
 101 .It
 102 ATTR_CMN_MODTIME
 103 .It
 104 ATTR_CMN_CHGTIME
 105 .It
 106 ATTR_CMN_ACCTIME
 107 .El
 108 .Pp
 109 .
 110 You must be root (that is, your process's effective UID must be 0) in order to change the
 111 .Dv ATTR_CMN_OWNERID
 112 attribute.
 113 Setting other attributes requires that you have write access to the object.
 114 .Pp
 115 .
 116 .\" attrList parameter
 117 .
 118 The
 119 .Fa attrList
 120 parameter is a pointer to an
 121 .Vt attrlist
 122 structure.
 123 You are responsible for filling out all fields of this structure before calling the function.
 124 See the discussion of the
 125 .Xr getattrlist 2
 126 function for a detailed description of this structure.
 127 To set an attribute you must set the corresponding bit in the appropriate
 128 .Vt attrgroup_t
 129 field of the
 130 .Vt attrlist
 131 structure.
 132 .Pp
 133 .
 134 .\" attrBuf and attrBufSize parameters
 135 .
 136 The
 137 .Fa attrBuf
 138 and
 139 .Fa attrBufSize
 140 parameters specify a buffer that contains the attribute values to set.
 141 Attributes are packed in exactly the same way as they are returned from
 142 .Xr getattrlist 2
 143 except that, when setting attributes, the buffer does not include the leading
 144 .Vt u_int32_t
 145 length value.
 146 .Pp
 147 .
 148 .\" option parameter
 149 .
 150 The
 151 .Fa options
 152 parameter is a bit set that controls the behaviour of
 153 .Fn setattrlist .
 154 The following option bits are defined.
 155 .
 156 .Bl -tag -width XXXbitmapcount
 157 .
 158 .It FSOPT_NOFOLLOW
 159 If this bit is set,
 160 .Fn setattrlist
 161 will not follow a symlink if it occurs as
 162 the last component of
 163 .Fa path .
 164 .
 165 .El
 166 .
 167 .Sh RETURN VALUES
 168 Upon successful completion a value of 0 is returned.
 169 Otherwise, a value of -1 is returned and
 170 .Va errno
 171 is set to indicate the error.
 172 .
 173 .Sh COMPATIBILITY
 174 Not all volumes support
 175 .Fn setattrlist .
 176 However, if a volume supports
 177 .Xr getattrlist 2 ,
 178 it must also support
 179 .Fn setattrlist .
 180 See the documentation for
 181 .Xr getattrlist 2
 182 for details on how to tell whether a volume supports it.
 183 .Pp
 184 .
 185 The
 186 .Fn setattrlist
 187 function has been undocumented for more than two years.
 188 In that time a number of volume format implementations have been created without
 189 a proper specification for the behaviour of this routine.
 190 You may encounter volume format implementations with slightly different
 191 behaviour than what is described here.
 192 Your program is expected to be tolerant of this variant behaviour.
 193 .Pp
 194 .
 195 If you're implementing a volume format that supports
 196 .Fn setattrlist ,
 197 you should be careful to support the behaviour specified by this document.
 198 .
 199 .Sh ERRORS
 200 .Fn setattrlist
 201 and
 202 .Fn fsetattrlist
 203 will fail if:
 204 .Bl -tag -width Er
 205 .
 206 .It Bq Er ENOTSUP
 207 The call is not supported by the volume.
 208 .
 209 .It Bq Er ENOTDIR
 210 A component of the path for
 211 .Fn setattrlist
 212 prefix is not a directory.
 213 .
 214 .It Bq Er ENAMETOOLONG
 215 A component of a path name for
 216 .Fn setattrlist
 217 exceeded
 218 .Dv NAME_MAX
 219 characters, or an entire path name exceeded
 220 .Dv PATH_MAX
 221 characters.
 222 .
 223 .It Bq Er ENOENT
 224 The file system object for
 225 .Fn setattrlist
 226 does not exist.
 227 .
 228 .It Bq Er EBADF
 229 The file descriptor argument for
 230 .Fn fsetattrlist
 231 is not a valid file descriptor.
 232 .
 233 .It Bq Er EROFS
 234 The volume is read-only.
 235 .
 236 .It Bq Er EACCES
 237 Search permission is denied for a component of the path prefix for
 238 .Fn setattrlist .
 239 .
 240 .It Bq Er ELOOP
 241 Too many symbolic links were encountered in translating the pathname for
 242 .Fn setattrlist .
 243 .
 244 .It Bq Er EFAULT
 245 .Fa path ,
 246 .Fa attrList
 247 or
 248 .Em attrBuf
 249 points to an invalid address.
 250 .
 251 .It Bq Er EINVAL
 252 The
 253 .Fa bitmapcount
 254 field of
 255 .Fa attrList
 256 is not
 257 .Dv ATTR_BIT_MAP_COUNT .
 258 .
 259 .It Bq Er EINVAL
 260 You try to set an invalid attribute.
 261 .
 262 .It Bq Er EINVAL
 263 You try to set an attribute that is read-only.
 264 .
 265 .It Bq Er EINVAL
 266 You try to set volume attributes and directory or file attributes at the same time.
 267 .
 268 .It Bq Er EINVAL
 269 You try to set volume attributes but
 270 .Fa path
 271 does not reference the root of the volume.
 272 .
 273 .It Bq Er EPERM
 274 You try to set an attribute that can only be set by the owner.
 275 .
 276 .It Bq Er EACCES
 277 You try to set an attribute that's only settable if you have write permission,
 278 and you do not have write permission.
 279 .
 280 .It Bq Er EINVAL
 281 The buffer size you specified in
 282 .Fa attrBufSize
 283 is too small to hold all the attributes that you are trying to set.
 284 .
 285 .It Bq Er EIO
 286 An I/O error occurred while reading from or writing to the file system.
 287 .El
 288 .Pp
 289 .
 290 .Sh CAVEATS
 291 .
 292 If you try to set any volume attributes, you must set
 293 .Dv ATTR_VOL_INFO
 294 in the
 295 .Fa volattr
 296 field, even though it consumes no data from the attribute buffer.
 297 .Pp
 298 .
 299 For more caveats, see also the compatibility notes above.
 300 .
 301 .Sh EXAMPLES
 302 .
 303 The following code shows how to set the file type and creator of
 304 a file by getting the
 305 .Dv ATTR_CMN_FNDRINFO
 306 attribute using
 307 .Xr getattrlist 2 ,
 308 modifying the appropriate fields of the 32-byte Finder information structure,
 309 and then setting the attribute back using
 310 .Fn setattrlist .
 311 This assumes that the target volume supports the required attributes
 312 .
 313 .Bd -literal
 314 #include <assert.h>
 315 #include <stdio.h>
 316 #include <stddef.h>
 317 #include <string.h>
 318 #include <sys/attr.h>
 319 #include <sys/errno.h>
 320 #include <unistd.h>
 321 #include <sys/vnode.h>
 322 .Pp
 323 .
 324 typedef struct attrlist attrlist_t;
 325 .Pp
 326 .
 327 struct FInfoAttrBuf {
 328     u_int32_t       length;
 329     fsobj_type_t    objType;
 330     char            finderInfo[32];
 331 };
 332 typedef struct FInfoAttrBuf FInfoAttrBuf;
 333 .Pp
 334 .
 335 static int FInfoDemo(
 336     const char *path,
 337     const char *type,
 338     const char *creator
 339 )
 340 {
 341     int             err;
 342     attrlist_t      attrList;
 343     FInfoAttrBuf    attrBuf;
 344 .Pp
 345
 346     assert( strlen(type)    == 4 );
 347     assert( strlen(creator) == 4 );
 348 .Pp
 349 .
 350     memset(&attrList, 0, sizeof(attrList));
 351     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
 352     attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
 353 .Pp
 354
 355     err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
 356     if (err != 0) {
 357         err = errno;
 358     }
 359 .Pp
 360
 361     if ( (err == 0) && (attrBuf.objType != VREG) ) {
 362         fprintf(stderr, "Not a standard file.\en");
 363         err = EINVAL;
 364     } else {
 365         memcpy( &attrBuf.finderInfo[0], type,    4 );
 366         memcpy( &attrBuf.finderInfo[4], creator, 4 );
 367
 368         attrList.commonattr = ATTR_CMN_FNDRINFO;
 369         err = setattrlist(
 370             path,
 371             &attrList,
 372             attrBuf.finderInfo,
 373             sizeof(attrBuf.finderInfo),
 374             0
 375         );
 376     }
 377 .Pp
 378     return err;
 379 }
 380 .Ed
 381 .Pp
 382 .
 383 .Sh SEE ALSO
 384 .
 385 .Xr chflags 2 ,
 386 .Xr chmod 2 ,
 387 .Xr chown 2 ,
 388 .Xr getattrlist 2 ,
 389 .Xr getdirentriesattr 2 ,
 390 .Xr searchfs 2 ,
 391 .Xr utimes 2
 392 .
 393 .Sh HISTORY
 394 A
 395 .Fn setattrlist
 396 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 397 .