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