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