]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/getattrlist.2
xnu-1228.7.58.tar.gz
[apple/xnu.git] / bsd / man / man2 / getattrlist.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 .\" @(#)getattrlist.2
18 .
19 .Dd October 14, 2004
20 .Dt GETATTRLIST 2
21 .Os Darwin
22 .Sh NAME
23 .Nm getattrlist
24 .Nd get file system attributes
25 .Sh SYNOPSIS
26 .Fd #include <sys/attr.h>
27 .Fd #include <unistd.h>
28 .Ft int
29 .Fn getattrlist "const char* path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
30 .
31 .Sh DESCRIPTION
32 The
33 .Fn getattrlist
34 function returns attributes (that is, metadata) of file system objects.
35 You can think of
36 .Fn getattrlist
37 as a seriously enhanced version of
38 .Xr stat 2 .
39 The function returns attributes about the file system object specified by
40 .Fa path
41 in the buffer specified by
42 .Fa attrBuf
43 and
44 .Fa attrBufSize .
45 The
46 .Fa attrList
47 parameter determines what attributes are returned.
48 The
49 .Fa options
50 parameter lets you control specific aspects of the function's behavior.
51 .Pp
52 .
53 The
54 .Fn getattrlist
55 function is only supported by certain volume format implementations.
56 For maximum compatibility, client programs should use high-level APIs
57 (such as the Carbon File Manager) to access file system attributes.
58 These high-level APIs include logic to emulate file system attributes
59 on volumes that don't support
60 .Fn getattrlist .
61 .Pp
62 .
63 Not all volumes support all attributes.
64 See the discussion of
65 .Dv ATTR_VOL_ATTRIBUTES
66 for a discussion of how to determine whether a particular volume supports a
67 particular attribute.
68 .Pp
69 Furthermore, you should only request the attributes that you need.
70 Some attributes are expensive to calculate on some volume formats.
71 For example,
72 .Dv ATTR_DIR_ENTRYCOUNT
73 is usually expensive to calculate on non-HFS [Plus] volumes.
74 If you don't need a particular attribute, you should not ask for it.
75 .Pp
76 .
77 .\" path parameter
78 .
79 The
80 .Fa path
81 parameter must reference a valid file system object.
82 Read, write or execute permission of the object itself is not required, but
83 all directories listed in the path name leading to the object must be
84 searchable.
85 .Pp
86 .
87 .\" attrList parameter
88 .
89 The
90 .Fa attrList
91 parameter is a pointer to an
92 .Vt attrlist
93 structure, as defined by
94 .Aq Pa sys/attr.h
95 (shown below).
96 It determines what attributes are returned by the function.
97 You are responsible for filling out all fields of this structure before calling the function.
98 .Bd -literal
99 typedef u_int32_t attrgroup_t;
100 .Pp
101 struct attrlist {
102 u_short bitmapcount; /* number of attr. bit sets in list */
103 u_int16_t reserved; /* (to maintain 4-byte alignment) */
104 attrgroup_t commonattr; /* common attribute group */
105 attrgroup_t volattr; /* volume attribute group */
106 attrgroup_t dirattr; /* directory attribute group */
107 attrgroup_t fileattr; /* file attribute group */
108 attrgroup_t forkattr; /* fork attribute group */
109 };
110 #define ATTR_BIT_MAP_COUNT 5
111 .Ed
112 .Pp
113 .
114 .\" attrlist elements
115 .
116 The fields of the
117 .Vt attrlist
118 structure are defined as follows.
119 .Bl -tag -width XXXbitmapcount
120 .
121 .It bitmapcount
122 Number of attribute bit sets in the structure.
123 In current systems you must set this to
124 .Dv ATTR_BIT_MAP_COUNT .
125 .
126 .It reserved
127 Reserved.
128 You must set this to 0.
129 .
130 .It commonattr
131 A bit set that specifies the common attributes that you require.
132 Common attributes relate to all types of file system objects.
133 See below for a description of these attributes.
134 .
135 .It volattr
136 A bit set that specifies the volume attributes that you require.
137 Volume attributes relate to volumes (that is, mounted file systems).
138 See below for a description of these attributes.
139 If you request volume attributes,
140 .Fa path
141 must reference the root of a volume.
142 In addition, you can't request volume attributes if you also request
143 file or directory attributes.
144 .
145 .It dirattr
146 A bit set that specifies the directory attributes that you require.
147 See below for a description of these attributes.
148 .
149 .It fileattr
150 A bit set that specifies the file attributes that you require.
151 See below for a description of these attributes.
152 .
153 .It forkattr
154 A bit set that specifies the fork attributes that you require.
155 Fork attributes relate to the actual data in the file,
156 which can be held in multiple named contiguous ranges, or forks.
157 See below for a description of these attributes.
158 .
159 .El
160 .Pp
161 .
162 Unless otherwise noted in the lists below, attributes are read-only.
163 Attributes labelled as read/write can be set using
164 .Xr setattrlist 2 .
165 .Pp
166 .
167 .\" attrBuf and attrBufSize parameters
168 .
169 The
170 .Fa attrBuf
171 and
172 .Fa attrBufSize
173 parameters specify a buffer into which the function places attribute values.
174 The format of this buffer is sufficiently complex that its description
175 requires a separate section (see below).
176 The initial contents of this buffer are ignored.
177 .Pp
178 .
179 .\" option parameter
180 .
181 The
182 .Fa options
183 parameter is a bit set that controls the behaviour of
184 .Fn getattrlist .
185 The following option bits are defined.
186 .
187 .Bl -tag -width XXXbitmapcount
188 .
189 .It FSOPT_NOFOLLOW
190 If this bit is set,
191 .Fn getattrlist
192 will not follow a symlink if it occurs as
193 the last component of
194 .Fa path .
195 .
196 .El
197 .
198 .Sh ATTRIBUTE BUFFER
199 .
200 The data returned in the buffer described by
201 .Fa attrBuf
202 and
203 .Fa attrBufSize
204 is formatted as follows.
205 .Pp
206 .
207 .Bl -enum
208 .
209 .It
210 The first element of the buffer is a
211 .Vt u_int32_t
212 that contains the overall length, in bytes, of the attributes returned.
213 This size includes the length field itself.
214 .
215 .It
216 Following the length field is a list of attributes.
217 Each attribute is represented by a field of its type,
218 where the type is given as part of the attribute description (below).
219 .
220 .It
221 The attributes are placed into the attribute buffer in the order
222 that they are described below.
223 .
224 .El
225 .Pp
226 .
227 If the attribute is of variable length, it is represented
228 in the list by an
229 .Vt attrreference
230 structure, as defined by
231 .Aq Pa sys/attr.h
232 (shown below).
233 .
234 .Bd -literal
235 typedef struct attrreference {
236 long attr_dataoffset;
237 size_t attr_length;
238 } attrreference_t;
239 .Ed
240 .Pp
241 .
242 This structure contains a 'pointer' to the variable length attribute data.
243 The
244 .Fa attr_length
245 field is the length of the attribute data (in bytes).
246 The
247 .Fa attr_dataoffset
248 field is the offset in bytes from the
249 .Vt attrreference
250 structure
251 to the attribute data.
252 This offset will always be a multiple of sizeof(unsigned long) bytes,
253 so you can safely access common data types without fear of alignment
254 exceptions.
255 .Pp
256 .
257 The
258 .Fn getattrlist
259 function will silently truncate attribute data if
260 .Fa attrBufSize
261 is too small.
262 The length field at the front of the attribute list always represents
263 the length of the data actually copied into the attribute buffer.
264 If the data is truncated, there is no easy way to determine the
265 buffer size that's required to get all of the requested attributes.
266 You should always pass an
267 .Fa attrBufSize
268 that is large enough to accommodate the known size of the attributes
269 in the attribute list (including the leading length field).
270 .Pp
271 .
272 Because the returned attributes are simply truncated if the buffer is
273 too small, it's possible for a variable length attribute to reference
274 data beyond the end of the attribute buffer. That is, it's possible
275 for the attribute data to start beyond the end of the attribute buffer
276 (that is, if
277 .Fa attrRef
278 is a pointer to the
279 .Vt attrreference_t ,
280 ( ( (char *)
281 .Fa attrRef
282 ) +
283 .Fa attr_dataoffset
284 ) > ( ( (char *)
285 .Fa attrBuf
286 ) +
287 .Fa attrSize
288 ) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is,
289 ( ( (char *)
290 .Fa attrRef
291 ) +
292 .Fa attr_dataoffset
293 +
294 .Fa attr_datalength
295 ) > ( ( (char *)
296 .Fa attrBuf
297 ) +
298 .Fa attrSize
299 ) ).
300 If this happens you must increase the size of the buffer and call
301 .Fn getattrlist
302 to get an accurate copy of the attribute.
303 .
304 .Sh COMMON ATTRIBUTES
305 .
306 Common attributes relate to all types of file system objects.
307 The following common attributes are defined.
308 .
309 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
310 .
311 .It ATTR_CMN_NAME
312 An
313 .Vt attrreference
314 structure containing the name of the file system object as
315 UTF-8 encoded, null terminated C string.
316 The attribute data length will not be greater than
317 .Dv NAME_MAX +
318 1.
319 .Pp
320 .
321 .It ATTR_CMN_DEVID
322 A
323 .Vt dev_t
324 containing the device number of the device on which this
325 file system object's volume is mounted.
326 Equivalent to the
327 .Fa st_dev
328 field of the
329 .Vt stat
330 structure returned by
331 .Xr stat 2 .
332 .
333 .It ATTR_CMN_FSID
334 An
335 .Vt fsid_t
336 structure containing the file system identifier for the volume on which
337 the file system object resides.
338 Equivalent to the
339 .Fa f_fsid
340 field of the
341 .Vt statfs
342 structure returned by
343 .Xr statfs 2 .
344 .
345 .Pp
346 This value is not related to the file system ID from traditional Mac OS (for example,
347 the
348 .Fa filesystemID
349 field of the
350 .Vt FSVolumeInfo
351 structure returned by Carbon's FSGetVolumeInfo() function).
352 On current versions of Mac OS X that value is synthesised by the Carbon File Manager.
353 .
354 .It ATTR_CMN_OBJTYPE
355 An
356 .Vt fsobj_type_t
357 that identifies the type of file system object.
358 The values are taken from
359 .Vt enum vtype
360 in
361 .Aq Pa sys/vnode.h .
362 .
363 .It ATTR_CMN_OBJTAG
364 An
365 .Vt fsobj_tag_t
366 that identifies the type of file system containing the object.
367 The values are taken from
368 .Vt enum vtagtype
369 in
370 .Aq Pa sys/vnode.h .
371 .
372 .It ATTR_CMN_OBJID
373 An
374 .Vt fsobj_id_t
375 structure that uniquely identifies the file system object
376 within its volume.
377 The fid_generation field of this structure will be zero for all non-root callers
378 (effective UID not 0).
379 This identifier need not be persistent across an unmount/mount sequence.
380 .Pp
381 .
382 Some volume formats use well known values for the
383 .Fa fid_objno
384 field for the root directory (2) and the parent of root directory (1).
385 This is not a required behaviour of this attribute.
386 .
387 .It ATTR_CMN_OBJPERMANENTID
388 An
389 .Vt fsobj_id_t
390 structure that uniquely identifies the file system object
391 within its volume.
392 The fid_generation field of this structure will be zero for all non-root callers
393 (effective UID not 0).
394 This identifier should be persistent across an unmount/mount sequence.
395 .Pp
396 Some file systems (for example, original HFS) may need to modify the on-disk
397 structure to return a persistent identifier.
398 If such a file system is mounted read-only, an attempt to get this attribute
399 will fail with the error
400 .Dv EROFS .
401 .
402 .It ATTR_CMN_PAROBJID
403 An
404 .Vt fsobj_id_t
405 structure that identifies the parent directory of the file system object.
406 The fid_generation field of this structure will be zero for all non-root callers
407 (effective UID not 0).
408 Equivalent to the ATTR_CMN_OBJID attribute of the parent directory.
409 This identifier need not be persistent across an unmount/mount sequence.
410 .Pp
411 .
412 On a volume that supports hard links, a multiply linked file has no unique parent.
413 This attribute will return an unspecified parent.
414 .Pp
415 .
416 For some volume formats this attribute is very expensive to calculate.
417 .
418 .It ATTR_CMN_SCRIPT
419 (read/write) A
420 .Vt text_encoding_t
421 containing a text encoding hint for
422 the file system object's name.
423 It is included to facilitate the lossless round trip conversion of names between
424 Unicode and traditional Mac OS script encodings.
425 The values are defined in
426 .Aq Pa CarbonCore/TextCommon.h .
427 File systems that do not have an appropriate text encoding value should return
428 kTextEncodingMacUnicode.
429 See DTS Q&A 1173 "File Manager Text Encoding Hints".
430 .
431 .It ATTR_CMN_CRTIME
432 (read/write) A
433 .Vt timespec
434 structure containing the time that the file system object
435 was created.
436 .
437 .It ATTR_CMN_MODTIME
438 (read/write) A
439 .Vt timespec
440 structure containing the time that the file system object
441 was last modified.
442 Equivalent to the
443 .Fa st_mtimespec
444 field of the
445 .Vt stat
446 structure returned by
447 .Xr stat 2 .
448 .
449 .It ATTR_CMN_CHGTIME
450 (read/write) A
451 .Vt timespec
452 structure containing the time that the file system object's
453 attributes were last modified.
454 Equivalent to the
455 .Fa st_ctimespec
456 field of the
457 .Vt stat
458 structure returned by
459 .Xr stat 2 .
460 .
461 .It ATTR_CMN_ACCTIME
462 (read/write) A
463 .Vt timespec
464 structure containing the time that the file system object
465 was last accessed.
466 Equivalent to the
467 .Fa st_atimespec
468 field of the
469 .Vt stat
470 structure returned by
471 .Xr stat 2 .
472 .
473 .It ATTR_CMN_BKUPTIME
474 (read/write) A
475 .Vt timespec
476 structure containing the time that the file system object was
477 last backed up.
478 This value is for use by backup utilities.
479 The file system stores but does not interpret the value.
480 .
481 .It ATTR_CMN_FNDRINFO
482 (read/write) 32 bytes of data for use by the Finder.
483 Equivalent to the concatenation of a
484 .Vt FileInfo
485 structure and an
486 .Vt ExtendedFileInfo
487 structure
488 (or, for directories, a
489 .Vt FolderInfo
490 structure and an
491 .Vt ExtendedFolderInfo
492 structure).
493 These structures are defined in
494 .Aq Pa CarbonCore/Finder.h .
495 .Pp
496 This attribute is not byte swapped by the file system.
497 The value of multibyte fields on disk is always big endian.
498 When running on a little endian system (such as Darwin on x86),
499 you must byte swap any multibyte fields.
500 .
501 .It ATTR_CMN_OWNERID
502 (read/write) A
503 .Vt uid_t
504 containing the owner of the file system object.
505 Equivalent to the
506 .Fa st_uid
507 field of the
508 .Vt stat
509 structure returned by
510 .Xr stat 2 .
511 .
512 .It ATTR_CMN_GRPID
513 (read/write) A
514 .Vt gid_t
515 containing the group of the file system object.
516 Equivalent to the
517 .Fa st_gid
518 field of the
519 .Vt stat
520 structure returned by
521 .Xr stat 2 .
522 .
523 .It ATTR_CMN_ACCESSMASK
524 (read/write) A
525 .Vt u_int32_t
526 containing the access permissions of the file system object.
527 Equivalent to the
528 .Fa st_mode
529 field of the
530 .Vt stat
531 structure returned by
532 .Xr stat 2 .
533 .
534 .It ATTR_CMN_NAMEDATTRCOUNT
535 A
536 .Vt u_int32_t
537 containing the number of named attributes of the file system object.
538 .
539 .It ATTR_CMN_NAMEDATTRLIST
540 An
541 .Vt attrreference
542 structure containing a list of named attributes of the file system object.
543 No built-in file systems on Mac OS X currently support named attributes.
544 Because of this, the structure of this attribute's value is not yet defined.
545 .
546 .It ATTR_CMN_FLAGS
547 (read/write) A
548 .Vt u_int32_t
549 containing file flags.
550 Equivalent to the
551 .Fa st_flags
552 field of the
553 .Vt stat
554 structure returned by
555 .Xr stat 2 .
556 For more information about these flags, see
557 .Xr chflags 2 .
558 .Pp
559 .
560 The order that attributes are placed into the attribute buffer
561 almost invariably matches the order of the attribute mask bit values.
562 The exception is
563 .Dv ATTR_CMN_FLAGS .
564 If its order was based on its bit position, it would be before
565 the
566 .Dv ATTR_CMN_NAMEDATTRCOUNT
567 /
568 .Dv ATTR_CMN_NAMEDATTRLIST
569 pair, however,
570 it is placed in the buffer after them.
571 .
572 .It ATTR_CMN_USERACCESS
573 A
574 .Vt u_int32_t
575 containing the effective permissions of the current user
576 (the calling process's effective UID) for this file system object.
577 You can test for read, write, and execute permission using
578 .Dv R_OK ,
579 .Dv W_OK ,
580 and
581 .Dv X_OK ,
582 respectively.
583 See
584 .Xr access 2
585 for more details.
586 .
587 .It ATTR_CMN_FILEID
588 A
589 .Vt u_int64_t
590 that uniquely identifies the file system object within its volume.
591 .
592 .It ATTR_CMN_PARENTID
593 A
594 .Vt u_int64_t
595 that identifies the parent directory of the file system object.
596 .
597 .El
598 .
599 .Sh VOLUME ATTRIBUTES
600 .
601 Volume attributes relate to volumes (that is, mounted file systems).
602 The following volume attributes are defined.
603 .
604 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
605 .
606 .It ATTR_VOL_INFO
607 For reasons that are not at all obvious, you must set
608 .Dv ATTR_VOL_INFO
609 in the
610 .Fa volattr
611 field if you request any other volume attributes.
612 This does not result in any attribute data being added to the attribute buffer.
613 .
614 .It ATTR_VOL_FSTYPE
615 A
616 .Vt u_int32_t
617 containing the file system type.
618 Equivalent to the
619 .Fa f_type
620 field of the
621 .Vt statfs
622 structure returned by
623 .Xr statfs 2 .
624 Generally not a useful value.
625 .
626 .It ATTR_VOL_SIGNATURE
627 A
628 .Vt u_int32_t
629 containing the volume signature word.
630 This value is unique within a given file system type and lets you
631 distinguish between different volume formats handled by the same file system.
632 See
633 .Aq Pa CarbonCore/Files.h
634 for more details.
635 .
636 .It ATTR_VOL_SIZE
637 An
638 .Vt off_t
639 containing the total size of the volume in bytes.
640 .
641 .It ATTR_VOL_SPACEFREE
642 An
643 .Vt off_t
644 containing the free space on the volume in bytes.
645 .
646 .It ATTR_VOL_SPACEAVAIL
647 An
648 .Vt off_t
649 containing the space, in bytes, on the volume available to non-privileged processes.
650 This is the free space minus the amount of space reserved by the system to prevent critical
651 disk exhaustion errors.
652 Non-privileged programs, like a disk management tool, should use this value to display the
653 space available to the user.
654 .Pp
655 .Dv ATTR_VOL_SPACEAVAIL
656 is to
657 .Dv ATTR_VOL_SPACEFREE
658 as
659 .Fa f_bavail
660 is to
661 .Fa f_bfree
662 in
663 .Xr statfs 2 .
664 .
665 .It ATTR_VOL_MINALLOCATION
666 An
667 .Vt off_t
668 containing the minimum allocation size on the volume in bytes.
669 If you create a file containing one byte, it will consume this much space.
670 .
671 .It ATTR_VOL_ALLOCATIONCLUMP
672 An
673 .Vt off_t
674 containing the allocation clump size on the volume, in bytes.
675 As a file is extended, the file system will attempt to allocate
676 this much space each time in order to reduce fragmentation.
677 .
678 .It ATTR_VOL_IOBLOCKSIZE
679 A
680 .Vt u_int32_t
681 containing the optimal block size when reading or writing data.
682 Equivalent to the
683 .Fa f_iosize
684 field of the
685 .Vt statfs
686 structure returned by
687 .Xr statfs 2 .
688 .
689 .It ATTR_VOL_OBJCOUNT
690 A
691 .Vt u_int32_t
692 containing the number of file system objects on the volume.
693 .
694 .It ATTR_VOL_FILECOUNT
695 A
696 .Vt u_int32_t
697 containing the number of files on the volume.
698 .
699 .It ATTR_VOL_DIRCOUNT
700 A
701 .Vt u_int32_t
702 containing the number of directories on the volume.
703 .
704 .It ATTR_VOL_MAXOBJCOUNT
705 A
706 .Vt u_int32_t
707 containing the maximum number of file system objects that can be stored on the volume.
708 .
709 .It ATTR_VOL_MOUNTPOINT
710 An
711 .Vt attrreference
712 structure containing the path to the volume's mount point as a
713 UTF-8 encoded, null terminated C string.
714 The attribute data length will not be greater than
715 .Dv MAXPATHLEN .
716 Equivalent to the
717 .Fa f_mntonname
718 field of the
719 .Vt statfs
720 structure returned by
721 .Xr statfs 2 .
722 .
723 .It ATTR_VOL_NAME
724 (read/write) An
725 .Vt attrreference
726 structure containing the name of the volume as a
727 UTF-8 encoded, null terminated C string.
728 The attribute data length will not be greater than
729 .Dv NAME_MAX +
730 1.
731 .Pp
732 .
733 This attribute is only read/write if the
734 .Dv VOL_CAP_INT_VOL_RENAME
735 bit is set in the volume capabilities (see below).
736 .Pp
737 .
738 .It ATTR_VOL_MOUNTFLAGS
739 A
740 .Vt u_int32_t
741 containing the volume mount flags.
742 This is a copy of the value passed to the
743 .Fa flags
744 parameter of
745 .Xr mount 2
746 when the volume was mounted.
747 Equivalent to the
748 .Fa f_flags
749 field of the
750 .Vt statfs
751 structure returned by
752 .Xr statfs 2 .
753 .
754 .It ATTR_VOL_MOUNTEDDEVICE
755 An
756 .Vt attrreference
757 structure that returns the same value as the
758 .Fa f_mntfromname
759 field of the
760 .Vt statfs
761 structure returned by
762 .Xr statfs 2 .
763 For local volumes this is the path to the device on which the volume is mounted as a
764 UTF-8 encoded, null terminated C string.
765 For network volumes, this is a unique string that identifies the mount.
766 The attribute data length will not be greater than
767 .Dv MAXPATHLEN .
768 .Pp
769 .
770 .It ATTR_VOL_ENCODINGSUSED
771 An
772 .Vt unsigned long long
773 containing a bitmap of the text encodings used on this volume.
774 For more information about this, see the discussion of
775 .Fa encodingsBitmap
776 in DTS Technote 1150 "HFS Plus Volume Format".
777 .
778 .It ATTR_VOL_CAPABILITIES
779 A
780 .Vt vol_capabilities_attr_t
781 structure describing the optional features supported by this volume.
782 See below for a discussion of volume capabilities.
783 .
784 .It ATTR_VOL_ATTRIBUTES
785 A
786 .Vt vol_attributes_attr_t
787 structure describing the attributes supported by this volume.
788 This structure is discussed below, along with volume capabilities.
789 .
790 .El
791 .
792 .Sh DIRECTORY ATTRIBUTES
793 .
794 The following directory attributes are defined.
795 .
796 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
797 .
798 .It ATTR_DIR_LINKCOUNT
799 A
800 .Vt u_int32_t
801 containing the number of hard links to the directory;
802 this does not include the historical "." and ".." entries.
803 For filesystems that do not support hard links to directories,
804 this value will be 1.
805 .
806 .It ATTR_DIR_ENTRYCOUNT
807 A
808 .Vt u_int32_t
809 containing the number of file system objects in the directory, not including
810 any synthetic items.
811 .
812 .It ATTR_DIR_MOUNTSTATUS
813 A
814 .Vt u_int32_t
815 containing flags describing what's mounted on the directory.
816 Currently the only flag defined is
817 .Dv DIR_MNTSTATUS_MNTPOINT,
818 which indicates that there is a file system mounted on this directory.
819 Due to a bug (r. 3502822), this flag is never set on current system.
820 .
821 .El
822 .
823 .Sh FILE ATTRIBUTES
824 .
825 The following file attributes are defined.
826 .
827 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
828 .
829 .It ATTR_FILE_LINKCOUNT
830 A
831 .Vt u_int32_t
832 containing the number of hard links to this file.
833 Equivalent to the
834 .Fa st_nlink
835 field of the
836 .Vt stat
837 structure returned by
838 .Xr stat 2 .
839 .
840 .It ATTR_FILE_TOTALSIZE
841 An
842 .Vt off_t
843 containing the total number of bytes in all forks of the file (the logical size).
844 .
845 .It ATTR_FILE_ALLOCSIZE
846 An
847 .Vt off_t
848 containing a count of the bytes on disk used by all of the file's forks (the physical size).
849 .
850 .It ATTR_FILE_IOBLOCKSIZE
851 A
852 .Vt u_int32_t
853 containing the optimal block size when reading or writing this file's data.
854 .
855 .It ATTR_FILE_CLUMPSIZE
856 A
857 .Vt u_int32_t
858 containing the allocation clump size for this file, in bytes.
859 As the file is extended, the file system will attempt to allocate
860 this much space each time in order to reduce fragmentation.
861 This value applies to the data fork.
862 .
863 .It ATTR_FILE_DEVTYPE
864 (read/write) A
865 .Vt u_int32_t
866 containing the device type for a special device file.
867 Equivalent to the
868 .Fa st_rdev
869 field of the
870 .Vt stat
871 structure returned by
872 .Xr stat 2 .
873 .
874 .It ATTR_FILE_FILETYPE
875 A
876 .Vt u_int32_t
877 that whose value is reserved.
878 Clients should ignore its value.
879 New volume format implementations should not support this attribute.
880 .
881 .It ATTR_FILE_FORKCOUNT
882 A
883 .Vt u_int32_t
884 containing the number of forks in the file.
885 No built-in file systems on Mac OS X currently support forks other
886 than the data and resource fork.
887 .
888 .It ATTR_FILE_FORKLIST
889 An
890 .Vt attrreference
891 structure containing a list of named forks of the file.
892 No built-in file systems on Mac OS X currently support forks
893 other than the data and resource fork.
894 Because of this, the structure of this attribute's value is not yet defined.
895 .
896 .It ATTR_FILE_DATALENGTH
897 An
898 .Vt off_t
899 containing the length of the data fork in bytes (the logical size).
900 .
901 .It ATTR_FILE_DATAALLOCSIZE
902 An
903 .Vt off_t
904 containing a count of the bytes on disk used by the data fork (the physical size).
905 .
906 .It ATTR_FILE_DATAEXTENTS
907 An
908 .Vt extentrecord
909 array for the data fork.
910 The array contains eight
911 .Vt diskextent
912 structures which represent the first
913 eight extents of the fork.
914 .Pp
915 This attributes exists for compatibility reasons.
916 New clients should not use this attribute.
917 Rather, they should use the
918 .Dv F_LOG2PHYS
919 command in
920 .Xr fcntl 2 .
921 .Pp
922 .
923 In current implementations the value may not be entirely accurate for
924 a variety of reasons.
925 .
926 .It ATTR_FILE_RSRCLENGTH
927 An
928 .Vt off_t
929 containing the length of the resource fork in bytes (the logical size).
930 .
931 .It ATTR_FILE_RSRCALLOCSIZE
932 An
933 .Vt off_t
934 containing a count of the bytes on disk used by the resource fork (the physical size).
935 .
936 .It ATTR_FILE_RSRCEXTENTS
937 An
938 .Vt extentrecord
939 array for the resource fork.
940 The array contains eight
941 .Vt diskextent
942 structures which represent the first
943 eight extents of the fork.
944 .Pp
945 See also
946 .Dv ATTR_FILE_DATAEXTENTS .
947 .
948 .El
949 .
950 .Sh FORK ATTRIBUTES
951 .
952 Fork attributes relate to the actual data in the file,
953 which can be held in multiple named contiguous ranges, or forks.
954 The following fork attributes are defined.
955 .
956 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
957 .
958 .It ATTR_FORK_TOTALSIZE
959 An
960 .Vt off_t
961 containing the length of the fork in bytes (the logical size).
962 .
963 .It ATTR_FORK_ALLOCSIZE
964 An
965 .Vt off_t
966 containing a count of the bytes on disk used by the fork (the physical size).
967 .
968 .El
969 .Pp
970 .
971 Fork attributes are not properly implemented by any current Mac OS X
972 volume format implementation.
973 We strongly recommend that client programs do not request fork attributes.
974 If you are implementing a volume format, you should not support these attributes.
975 .
976 .Sh VOLUME CAPABILITIES
977 .
978 .\" vol_capabilities_attr_t
979 .
980 Not all volumes support all features.
981 The
982 .Dv ATTR_VOL_CAPABILITIES
983 attribute returns a
984 .Vt vol_capabilities_attr_t
985 structure (shown below) that indicates which features are supported by the volume.
986 .
987 .Bd -literal
988 typedef u_int32_t vol_capabilities_set_t[4];
989 .Pp
990 .
991 #define VOL_CAPABILITIES_FORMAT 0
992 #define VOL_CAPABILITIES_INTERFACES 1
993 #define VOL_CAPABILITIES_RESERVED1 2
994 #define VOL_CAPABILITIES_RESERVED2 3
995 .Pp
996 .
997 typedef struct vol_capabilities_attr {
998 vol_capabilities_set_t capabilities;
999 vol_capabilities_set_t valid;
1000 } vol_capabilities_attr_t;
1001 .Ed
1002 .Pp
1003 .
1004 The structure contains two fields,
1005 .Fa capabilities
1006 and
1007 .Fa valid .
1008 Each consists of an array of four elements.
1009 The arrays are indexed by the following values.
1010 .
1011 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1012 .
1013 .It VOL_CAPABILITIES_FORMAT
1014 This element contains information about the volume format.
1015 See
1016 .Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
1017 and so on, below.
1018 .
1019 .It VOL_CAPABILITIES_INTERFACES
1020 This element contains information about which optional functions are
1021 supported by the volume format implementation.
1022 See
1023 .Dv VOL_CAP_INT_SEARCHFS
1024 and so on, below.
1025 .
1026 .It VOL_CAPABILITIES_RESERVED1
1027 Reserved.
1028 A file system implementation should set this element to zero.
1029 A client program should ignore this element.
1030 .
1031 .It VOL_CAPABILITIES_RESERVED2
1032 Reserved.
1033 A file system implementation should set this element to zero.
1034 A client program should ignore this element.
1035 .
1036 .El
1037 .Pp
1038 .
1039 The
1040 .Fa valid
1041 field contains bit sets that indicate which flags are known to the volume format
1042 implementation.
1043 Each bit indicates whether the contents of the corresponding bit in the
1044 .Fa capabilities
1045 field is valid.
1046 .Pp
1047 .
1048 The
1049 .Fa capabilities
1050 field contains bit sets that indicate whether a particular feature is implemented
1051 by this volume format.
1052 .Pp
1053 .
1054 The following bits are defined in the first element (indexed by
1055 .Dv VOL_CAPABILITIES_FORMAT )
1056 of the
1057 .Fa capabilities
1058 and
1059 .Fa valid
1060 fields of the
1061 .Vt vol_capabilities_attr_t
1062 structure.
1063 .
1064 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1065 .
1066 .It VOL_CAP_FMT_PERSISTENTOBJECTIDS
1067 If this bit is set the volume format supports persistent object identifiers
1068 and can look up file system objects by their IDs.
1069 See
1070 .Dv ATTR_CMN_OBJPERMANENTID
1071 for details about how to obtain these identifiers.
1072 .
1073 .It VOL_CAP_FMT_SYMBOLICLINKS
1074 If this bit is set the volume format supports symbolic links.
1075 .
1076 .It VOL_CAP_FMT_HARDLINKS
1077 If this bit is set the volume format supports hard links.
1078 .
1079 .It VOL_CAP_FMT_JOURNAL
1080 If this bit is set the volume format supports a journal used to
1081 speed recovery in case of unplanned restart (such as a power outage
1082 or crash).
1083 This does not necessarily mean the volume is actively using a journal.
1084 .Pp
1085 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1086 .
1087 .It VOL_CAP_FMT_JOURNAL_ACTIVE
1088 If this bit is set the volume is currently using a journal for
1089 speedy recovery after an unplanned restart.
1090 This bit can be set only if
1091 .Dv VOL_CAP_FMT_JOURNAL
1092 is also set.
1093 .Pp
1094 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1095 .
1096 .It VOL_CAP_FMT_NO_ROOT_TIMES
1097 If this bit is set the volume format does not store reliable times for
1098 the root directory, so you should not depend on them to detect changes,
1099 identify volumes across unmount/mount, and so on.
1100 .Pp
1101 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1102 .
1103 .It VOL_CAP_FMT_SPARSE_FILES
1104 If this bit is set the volume format supports sparse files,
1105 that is, files which can have 'holes' that have never been written
1106 to, and thus do not consume space on disk.
1107 A sparse file may have an allocated size on disk that is less than its logical length (that is,
1108 .Dv ATTR_FILE_ALLOCSIZE
1109 <
1110 .Dv ATTR_FILE_TOTALSIZE ).
1111 .
1112 .Pp
1113 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1114 .
1115 .It VOL_CAP_FMT_ZERO_RUNS
1116 For security reasons, parts of a file (runs) that have never been
1117 written to must appear to contain zeroes.
1118 When this bit is set, the volume keeps track of allocated but unwritten
1119 runs of a file so that it can substitute zeroes without actually
1120 writing zeroes to the media.
1121 This provides performance similar to sparse files, but not the space savings.
1122 .Pp
1123 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1124 .
1125 .It VOL_CAP_FMT_CASE_SENSITIVE
1126 If this bit is set the volume format treats upper and lower case
1127 characters in file and directory names as different.
1128 Otherwise an upper case character is equivalent to a lower case character,
1129 and you can't have two names that differ solely in the case of
1130 the characters.
1131 .Pp
1132 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1133 .
1134 .It VOL_CAP_FMT_CASE_PRESERVING
1135 If this bit is set the volume format preserves the case of
1136 file and directory names.
1137 Otherwise the volume may change the case of some characters
1138 (typically making them all upper or all lower case).
1139 A volume that sets
1140 .Dv VOL_CAP_FMT_CASE_SENSITIVE
1141 must also set
1142 .Dv VOL_CAP_FMT_CASE_PRESERVING .
1143 .Pp
1144 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1145 .
1146 .It VOL_CAP_FMT_FAST_STATFS
1147 This bit is used as a hint to upper layers (specifically the Carbon File Manager) to
1148 indicate that
1149 .Xr statfs 2
1150 is fast enough that its results need not be cached by the caller.
1151 A volume format implementation that caches the
1152 .Xr statfs 2
1153 information in memory should set this bit.
1154 An implementation that must always read from disk or always perform a network
1155 transaction to satisfy
1156 .Xr statfs 2
1157 should not set this bit.
1158 .Pp
1159 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1160 .
1161 .It VOL_CAP_FMT_2TB_FILESIZE
1162 If this bit is set the volume format supports file
1163 sizes upto 2TB. This bit does not necessarily mean that the file
1164 system does not support file size more than 2TB.
1165 This bit does not mean that the currently available space on the volume is 2TB.
1166 .Pp
1167 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1168 .
1169 .El
1170 .Pp
1171 .
1172 The following bits are defined in the second element (indexed by
1173 .Dv VOL_CAPABILITIES_INTERFACES )
1174 of the
1175 .Fa capabilities
1176 and
1177 .Fa valid
1178 fields of the
1179 .Vt vol_capabilities_attr_t
1180 structure.
1181 .
1182 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1183 .
1184 .It VOL_CAP_INT_SEARCHFS
1185 If this bit is set the volume format implementation supports
1186 .Xr searchfs 2 .
1187 .
1188 .It VOL_CAP_INT_ATTRLIST
1189 If this bit is set the volume format implementation supports
1190 .Fn getattrlist
1191 and
1192 .Xr setattrlist 2 .
1193 .
1194 .It VOL_CAP_INT_NFSEXPORT
1195 If this bit is set the volume format implementation allows this volume to be exported via NFS.
1196 .
1197 .It VOL_CAP_INT_READDIRATTR
1198 If this bit is set the volume format implementation supports
1199 .Xr getdirentriesattr 2 .
1200 .
1201 .It VOL_CAP_INT_EXCHANGEDATA
1202 If this bit is set the volume format implementation supports
1203 .Xr exchangedata 2 .
1204 .Pp
1205 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1206 .
1207 .It VOL_CAP_INT_COPYFILE
1208 If this bit is set the volume format implementation supports the (private and undocumented)
1209 copyfile() function.
1210 .Pp
1211 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1212 .
1213 .It VOL_CAP_INT_ALLOCATE
1214 If this bit is set the volume format implementation supports the
1215 .Dv F_PREALLOCATE
1216 selector of
1217 .Xr fcntl 2 .
1218 .Pp
1219 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1220 .
1221 .It VOL_CAP_INT_VOL_RENAME
1222 If this bit is set the volume format implementation allows you to
1223 modify the volume name using
1224 .Xr setattrlist 2 .
1225 .Pp
1226 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1227 .
1228 .It VOL_CAP_INT_ADVLOCK
1229 If this bit is set the volume format implementation supports
1230 advisory locking, that is, the
1231 .Dv F_GETLK ,
1232 .Dv F_SETLK ,
1233 and
1234 .Dv F_SETLKW
1235 selectors to
1236 .Xr fcntl 2 .
1237 .Pp
1238 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1239 .
1240 .It VOL_CAP_INT_FLOCK
1241 If this bit is set the volume format implementation supports
1242 whole file locks.
1243 This includes
1244 .Xr flock 2
1245 and the
1246 .Dv O_EXLOCK
1247 and
1248 .Dv O_SHLOCK
1249 flags to
1250 .Xr open 2 .
1251 .Pp
1252 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1253 .
1254 .It VOL_CAP_INT_EXTENDED_SECURITY
1255 If this bit is set the volume format implementation supports
1256 extended security controls (ACLs).
1257 .Pp
1258 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1259 .
1260 .It VOL_CAP_INT_USERACCESS
1261 If this bit is set the volume format implementation supports the
1262 ATTR_CMN_USERACCESS attribute.
1263 .Pp
1264 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1265 .
1266 .El
1267 .Pp
1268 .
1269 .\" vol_attributes_attr_t
1270 .
1271 A volume can also report which attributes it supports.
1272 This information is returned by the
1273 .Dv ATTR_VOL_ATTRIBUTES
1274 attribute, which returns a
1275 .Vt vol_attributes_attr_t
1276 structure (shown below).
1277 .
1278 .Bd -literal
1279 typedef struct attribute_set {
1280 attrgroup_t commonattr; /* common attribute group */
1281 attrgroup_t volattr; /* volume attribute group */
1282 attrgroup_t dirattr; /* directory attribute group */
1283 attrgroup_t fileattr; /* file attribute group */
1284 attrgroup_t forkattr; /* fork attribute group */
1285 } attribute_set_t;
1286 .Pp
1287 .
1288 typedef struct vol_attributes_attr {
1289 attribute_set_t validattr;
1290 attribute_set_t nativeattr;
1291 } vol_attributes_attr_t;
1292 .Ed
1293 .Pp
1294 .
1295 The
1296 .Fa validattr
1297 field consists of a number of bit sets that indicate whether an attribute is
1298 supported by the volume format implementation.
1299 The
1300 .Fa nativeattr
1301 is similar except that the bit sets indicate whether an attribute is supported
1302 natively by the volume format.
1303 An attribute is supported natively if the volume format implementation does not have to do
1304 any complex conversions to access the attribute.
1305 For example, a volume format might support persistent object identifiers, but
1306 doing so requires a complex table lookup that is not part of the core volume
1307 format.
1308 In that case, the
1309 .Dv ATTR_VOL_ATTRIBUTES
1310 attribute would return
1311 .Dv ATTR_CMN_OBJPERMANENTID
1312 set in the
1313 .Fa validattr
1314 field of the
1315 .Vt vol_attributes_attr_t ,
1316 but not in the
1317 .Fa nativeattr
1318 field.
1319 .
1320 .Sh RETURN VALUES
1321 Upon successful completion a value of 0 is returned.
1322 Otherwise, a value of -1 is returned and
1323 .Va errno
1324 is set to indicate the error.
1325 .
1326 .Sh COMPATIBILITY
1327 Not all volumes support
1328 .Fn getattrlist .
1329 The best way to test whether a volume supports this function is to
1330 simply call it and check the error result.
1331 .Fn getattrlist
1332 will return
1333 .Dv ENOTSUP
1334 if it is not supported on a particular volume.
1335 .Pp
1336 .
1337 The
1338 .Fn getattrlist
1339 function has been undocumented for more than two years.
1340 In that time a number of volume format implementations have been created without
1341 a proper specification for the behaviour of this routine.
1342 You may encounter volume format implementations with slightly different
1343 behaviour than what is described here.
1344 Your program is expected to be tolerant of this variant behaviour.
1345 .Pp
1346 .
1347 If you're implementing a volume format that supports
1348 .Fn getattrlist ,
1349 you should be careful to support the behaviour specified by this document.
1350 .
1351 .Sh ERRORS
1352 .Fn getattrlist
1353 will fail if:
1354 .Bl -tag -width Er
1355 .
1356 .It Bq Er ENOTSUP
1357 The volume does not support
1358 .Fn getattrlist .
1359 .
1360 .It Bq Er ENOTDIR
1361 A component of the path prefix is not a directory.
1362 .
1363 .It Bq Er ENAMETOOLONG
1364 A component of a path name exceeded
1365 .Dv NAME_MAX
1366 characters, or an entire path name exceeded
1367 .Dv PATH_MAX
1368 characters.
1369 .
1370 .It Bq Er ENOENT
1371 The file system object does not exist.
1372 .
1373 .It Bq Er EACCES
1374 Search permission is denied for a component of the path prefix.
1375 .
1376 .It Bq Er ELOOP
1377 Too many symbolic links were encountered in translating the pathname.
1378 .
1379 .It Bq Er EFAULT
1380 .Fa path ,
1381 .Fa attrList
1382 or
1383 .Em attrBuf
1384 points to an invalid address.
1385 .
1386 .It Bq Er EINVAL
1387 The
1388 .Fa bitmapcount
1389 field of
1390 .Fa attrList
1391 is not
1392 .Dv ATTR_BIT_MAP_COUNT .
1393 .
1394 .It Bq Er EINVAL
1395 You requested an invalid attribute.
1396 .
1397 .It Bq Er EINVAL
1398 You requested an attribute that is not supported for this file system object.
1399 .
1400 .It Bq Er EINVAL
1401 You requested volume attributes and directory or file attributes.
1402 .
1403 .It Bq Er EINVAL
1404 You requested volume attributes but
1405 .Fa path
1406 does not reference the root of the volume.
1407 .
1408 .It Bq Er EROFS
1409 The volume is read-only but must be modified in order to return this attribute.
1410 .
1411 .It Bq Er EIO
1412 An I/O error occurred while reading from or writing to the file system.
1413 .El
1414 .Pp
1415 .
1416 .Sh CAVEATS
1417 .
1418 If you request any volume attributes, you must set
1419 .Dv ATTR_VOL_INFO
1420 in the
1421 .Fa volattr
1422 field, even though it generates no result in the attribute buffer.
1423 .Pp
1424 .
1425 The order that attributes are stored in the attribute buffer almost
1426 invariably matches the order of attribute mask bit values.
1427 For example,
1428 .Dv ATTR_CMN_NAME
1429 (0x00000001) comes before
1430 .Dv ATTR_CMN_DEVID
1431 (0x00000002) because its value is smaller.
1432 However, you can not rely on this ordering because there is one key exception:
1433 .Dv ATTR_CMN_FLAGS
1434 is placed after the
1435 .Dv ATTR_CMN_NAMEDATTRCOUNT
1436 /
1437 .Dv ATTR_CMN_NAMEDATTRLIST
1438 pair, even though its bit position indicates that it should come before.
1439 This is due to a bug in an early version of Mac OS X that can't be fixed for
1440 binary compatibility reasons.
1441 When ordering attributes, you should always use the order in which they
1442 are described above.
1443 .Pp
1444 .
1445 For more caveats, see also the compatibility notes above.
1446 .
1447 .Sh EXAMPLES
1448 .
1449 The following code prints the file type and creator of a file,
1450 assuming that the volume supports the required attributes.
1451 .
1452 .Bd -literal
1453 #include <assert.h>
1454 #include <stdio.h>
1455 #include <string.h>
1456 #include <sys/attr.h>
1457 #include <sys/errno.h>
1458 #include <unistd.h>
1459 #include <sys/vnode.h>
1460 .Pp
1461 .
1462 typedef struct attrlist attrlist_t;
1463 .Pp
1464 .
1465 struct FInfoAttrBuf {
1466 u_int32_t length;
1467 fsobj_type_t objType;
1468 char finderInfo[32];
1469 };
1470 typedef struct FInfoAttrBuf FInfoAttrBuf;
1471 .Pp
1472 .
1473 static int FInfoDemo(const char *path)
1474 {
1475 int err;
1476 attrlist_t attrList;
1477 FInfoAttrBuf attrBuf;
1478 .Pp
1479 .
1480 memset(&attrList, 0, sizeof(attrList));
1481 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1482 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1483 .Pp
1484
1485 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1486 if (err != 0) {
1487 err = errno;
1488 }
1489 .Pp
1490
1491 if (err == 0) {
1492 assert(attrBuf.length == sizeof(attrBuf));
1493 .Pp
1494
1495 printf("Finder information for %s:\en", path);
1496 switch (attrBuf.objType) {
1497 case VREG:
1498 printf("file type = '%.4s'\en", &attrBuf.finderInfo[0]);
1499 printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
1500 break;
1501 case VDIR:
1502 printf("directory\en");
1503 break;
1504 default:
1505 printf("other object type, %d\en", attrBuf.objType);
1506 break;
1507 }
1508 }
1509 .Pp
1510 .
1511 return err;
1512 }
1513 .Ed
1514 .Pp
1515 .
1516 The following code is an alternative implementation that uses nested structures
1517 to group the related attributes.
1518 .
1519 .Bd -literal
1520 #include <assert.h>
1521 #include <stdio.h>
1522 #include <stddef.h>
1523 #include <string.h>
1524 #include <sys/attr.h>
1525 #include <sys/errno.h>
1526 #include <unistd.h>
1527 #include <sys/vnode.h>
1528 .Pp
1529 .
1530 typedef struct attrlist attrlist_t;
1531 .Pp
1532 .
1533 struct FInfo2CommonAttrBuf {
1534 fsobj_type_t objType;
1535 char finderInfo[32];
1536 };
1537 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
1538 .Pp
1539 .
1540 struct FInfo2AttrBuf {
1541 u_int32_t length;
1542 FInfo2CommonAttrBuf common;
1543 };
1544 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
1545 .Pp
1546 .
1547 static int FInfo2Demo(const char *path)
1548 {
1549 int err;
1550 attrlist_t attrList;
1551 FInfo2AttrBuf attrBuf;
1552 .Pp
1553 .
1554 memset(&attrList, 0, sizeof(attrList));
1555 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1556 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1557 .Pp
1558 .
1559 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1560 if (err != 0) {
1561 err = errno;
1562 }
1563 .Pp
1564 .
1565 if (err == 0) {
1566 assert(attrBuf.length == sizeof(attrBuf));
1567 .Pp
1568 .
1569 printf("Finder information for %s:\en", path);
1570 switch (attrBuf.common.objType) {
1571 case VREG:
1572 printf(
1573 "file type = '%.4s'\en",
1574 &attrBuf.common.finderInfo[0]
1575 );
1576 printf(
1577 "file creator = '%.4s'\en",
1578 &attrBuf.common.finderInfo[4]
1579 );
1580 break;
1581 case VDIR:
1582 printf("directory\en");
1583 break;
1584 default:
1585 printf(
1586 "other object type, %d\en",
1587 attrBuf.common.objType
1588 );
1589 break;
1590 }
1591 }
1592 .Pp
1593 .
1594 return err;
1595 }
1596 .Ed
1597 .Pp
1598 .
1599 The following example shows how to deal with variable length attributes.
1600 It assumes that the volume specified by
1601 .Fa path
1602 supports the necessary attributes.
1603 .
1604 .Bd -literal
1605 #include <assert.h>
1606 #include <stdio.h>
1607 #include <stddef.h>
1608 #include <string.h>
1609 #include <sys/attr.h>
1610 #include <sys/errno.h>
1611 #include <unistd.h>
1612 #include <sys/vnode.h>
1613 .Pp
1614 .
1615 typedef struct attrlist attrlist_t;
1616 .Pp
1617 .
1618 struct VolAttrBuf {
1619 u_int32_t length;
1620 u_int32_t fileCount;
1621 u_int32_t dirCount;
1622 attrreference_t mountPointRef;
1623 attrreference_t volNameRef;
1624 char mountPointSpace[MAXPATHLEN];
1625 char volNameSpace[MAXPATHLEN];
1626 };
1627 typedef struct VolAttrBuf VolAttrBuf;
1628 .Pp
1629 .
1630 static int VolDemo(const char *path)
1631 {
1632 int err;
1633 attrlist_t attrList;
1634 VolAttrBuf attrBuf;
1635 .Pp
1636 .
1637 memset(&attrList, 0, sizeof(attrList));
1638 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1639 attrList.volattr = ATTR_VOL_INFO
1640 | ATTR_VOL_FILECOUNT
1641 | ATTR_VOL_DIRCOUNT
1642 | ATTR_VOL_MOUNTPOINT
1643 | ATTR_VOL_NAME;
1644 .Pp
1645
1646 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1647 if (err != 0) {
1648 err = errno;
1649 }
1650 .Pp
1651
1652 if (err == 0) {
1653 assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace));
1654 assert(attrBuf.length <= sizeof(attrBuf));
1655 .Pp
1656
1657 printf("Volume information for %s:\en", path);
1658 printf("ATTR_VOL_FILECOUNT: %lu\en", attrBuf.fileCount);
1659 printf("ATTR_VOL_DIRCOUNT: %lu\en", attrBuf.dirCount);
1660 printf(
1661 "ATTR_VOL_MOUNTPOINT: %.*s\en",
1662 (int) attrBuf.mountPointRef.attr_length,
1663 ( ((char *) &attrBuf.mountPointRef)
1664 + attrBuf.mountPointRef.attr_dataoffset )
1665 );
1666 printf(
1667 "ATTR_VOL_NAME: %.*s\en",
1668 (int) attrBuf.volNameRef.attr_length,
1669 ( ((char *) &attrBuf.volNameRef)
1670 + attrBuf.volNameRef.attr_dataoffset )
1671 );
1672 }
1673 .Pp
1674 .
1675 return err;
1676 }
1677 .Ed
1678 .Pp
1679 .
1680 .Sh SEE ALSO
1681 .
1682 .Xr access 2 ,
1683 .Xr chflags 2 ,
1684 .Xr exchangedata 2 ,
1685 .Xr fcntl 2 ,
1686 .Xr getdirentriesattr 2 ,
1687 .Xr mount 2 ,
1688 .Xr searchfs 2 ,
1689 .Xr setattrlist 2 ,
1690 .Xr stat 2 ,
1691 .Xr statfs 2
1692 .
1693 .Sh HISTORY
1694 A
1695 .Fn getattrlist
1696 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
1697 .