]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man2/setattrlist.2
xnu-4903.270.47.tar.gz
[apple/xnu.git] / bsd / man / man2 / setattrlist.2
... / ...
CommitLineData
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.
188You must be root (that is, your process's effective UID must be 0) in order to change the
189.Dv ATTR_CMN_OWNERID
190attribute
191Setting other attributes requires that you have write access to the object.
192.Pp
193.
194.\" attrList parameter
195.
196The
197.Fa attrList
198parameter is a pointer to an
199.Vt attrlist
200structure.
201You are responsible for filling out all fields of this structure before calling the function.
202See the discussion of the
203.Xr getattrlist 2
204function for a detailed description of this structure.
205To set an attribute you must set the corresponding bit in the appropriate
206.Vt attrgroup_t
207field of the
208.Vt attrlist
209structure.
210.Pp
211.
212.\" attrBuf and attrBufSize parameters
213.
214The
215.Fa attrBuf
216and
217.Fa attrBufSize
218parameters specify a buffer that contains the attribute values to set.
219Attributes are packed in exactly the same way as they are returned from
220.Xr getattrlist 2
221except that, when setting attributes, the buffer does not include the leading
222.Vt u_int32_t
223length value.
224.Pp
225.
226.\" option parameter
227.
228The
229.Fa options
230parameter is a bit set that controls the behaviour of
231.Fn setattrlist .
232The following option bits are defined.
233.
234.Bl -tag -width XXXbitmapcount
235.
236.It FSOPT_NOFOLLOW
237If this bit is set,
238.Fn setattrlist
239will not follow a symlink if it occurs as
240the last component of
241.Fa path .
242.
243.El
244.
245.Sh RETURN VALUES
246Upon successful completion a value of 0 is returned.
247Otherwise, a value of -1 is returned and
248.Va errno
249is set to indicate the error.
250.
251.Sh COMPATIBILITY
252Not all volumes support
253.Fn setattrlist .
254However, if a volume supports
255.Xr getattrlist 2 ,
256it must also support
257.Fn setattrlist .
258See the documentation for
259.Xr getattrlist 2
260for details on how to tell whether a volume supports it.
261.Pp
262.
263The
264.Fn setattrlist
265function has been undocumented for more than two years.
266In that time a number of volume format implementations have been created without
267a proper specification for the behaviour of this routine.
268You may encounter volume format implementations with slightly different
269behaviour than what is described here.
270Your program is expected to be tolerant of this variant behaviour.
271.Pp
272.
273If you're implementing a volume format that supports
274.Fn setattrlist ,
275you should be careful to support the behaviour specified by this document.
276.
277.Sh ERRORS
278.Fn setattrlist
279and
280.Fn fsetattrlist
281will fail if:
282.Bl -tag -width Er
283.
284.It Bq Er ENOTSUP
285The call is not supported by the volume.
286.
287.It Bq Er ENOTDIR
288A component of the path for
289.Fn setattrlist
290prefix is not a directory.
291.
292.It Bq Er ENAMETOOLONG
293A component of a path name for
294.Fn setattrlist
295exceeded
296.Dv NAME_MAX
297characters, or an entire path name exceeded
298.Dv PATH_MAX
299characters.
300.
301.It Bq Er ENOENT
302The file system object for
303.Fn setattrlist
304does not exist.
305.
306.It Bq Er EBADF
307The file descriptor argument for
308.Fn fsetattrlist
309is not a valid file descriptor.
310.
311.It Bq Er EROFS
312The volume is read-only.
313.
314.It Bq Er EACCES
315Search permission is denied for a component of the path prefix for
316.Fn setattrlist .
317.
318.It Bq Er ELOOP
319Too 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
325or
326.Em attrBuf
327points to an invalid address.
328.
329.It Bq Er EINVAL
330The
331.Fa bitmapcount
332field of
333.Fa attrList
334is not
335.Dv ATTR_BIT_MAP_COUNT .
336.
337.It Bq Er EINVAL
338You try to set an invalid attribute.
339.
340.It Bq Er EINVAL
341You try to set an attribute that is read-only.
342.
343.It Bq Er EINVAL
344You try to set volume attributes and directory or file attributes at the same time.
345.
346.It Bq Er EINVAL
347You try to set volume attributes but
348.Fa path
349does not reference the root of the volume.
350.
351.It Bq Er EPERM
352You try to set an attribute that can only be set by the owner.
353.
354.It Bq Er EACCES
355You try to set an attribute that's only settable if you have write permission,
356and you do not have write permission.
357.
358.It Bq Er EINVAL
359The buffer size you specified in
360.Fa attrBufSize
361is too small to hold all the attributes that you are trying to set.
362.
363.It Bq Er EIO
364An I/O error occurred while reading from or writing to the file system.
365.El
366.Pp
367.Pp
368In addition to the errors returned by the
369.Fn setattrlist ,
370the
371.Fn setattrlistat
372function may fail if:
373.Bl -tag -width Er
374.It Bq Er EBADF
375The
376.Fa path
377argument does not specify an absolute path and the
378.Fa fd
379argument is neither
380.Dv AT_FDCWD
381nor a valid file descriptor open for searching.
382.It Bq Er ENOTDIR
383The
384.Fa path
385argument is not an absolute path and
386.Fa fd
387is neither
388.Dv AT_FDCWD
389nor a file descriptor associated with a directory.
390.El
391.Pp
392.
393.Sh CAVEATS
394.
395If you try to set any volume attributes, you must set
396.Dv ATTR_VOL_INFO
397in the
398.Fa volattr
399field, even though it consumes no data from the attribute buffer.
400.Pp
401.
402For more caveats, see also the compatibility notes above.
403.
404.Sh EXAMPLES
405.
406The following code shows how to set the file type and creator of
407a file by getting the
408.Dv ATTR_CMN_FNDRINFO
409attribute using
410.Xr getattrlist 2 ,
411modifying the appropriate fields of the 32-byte Finder information structure,
412and then setting the attribute back using
413.Fn setattrlist .
414This 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.
427typedef struct attrlist attrlist_t;
428.Pp
429.
430struct FInfoAttrBuf {
431 u_int32_t length;
432 fsobj_type_t objType;
433 char finderInfo[32];
434};
435typedef struct FInfoAttrBuf FInfoAttrBuf;
436.Pp
437.
438static 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
497A
498.Fn setattrlist
499function call appeared in Darwin 1.3.1 (Mac OS X version 10.0). The setatrlistat function call first
500appeared in macOS version 10.13.
501.