1 .\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
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.
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.
26 .Nd get file system attributes
28 .Fd #include <sys/attr.h>
29 .Fd #include <unistd.h>
31 .Fn getattrlist "const char* path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
34 .Fn fgetattrlist "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
37 .Fa "int fd" "const char *path" "struct attrlist * attrList" "void * attrBuf"
38 .Fa "size_t attrBufSize" "unsigned long options"
43 function returns attributes (that is, metadata) of file system objects.
45 works on the file system object named by
49 works on the provided file descriptor
54 system call is equivalent to
56 except in the case where
58 specifies a relative path.
59 In this case the attributes are returned for the file system object named by
60 path relative to the directory associated with the file descriptor
62 instead of the current working directory.
65 is passed the special value
69 parameter, the current working directory is used and the behavior is
70 identical to a call to
75 as a seriously enhanced version of
77 The functions return attributes about the specified file system object
78 into the buffer specified by
84 parameter determines what attributes are returned.
87 parameter lets you control specific aspects of the function's behavior.
90 Not all volumes support all attributes.
92 .Dv ATTR_VOL_ATTRIBUTES
93 for a discussion of how to determine whether a particular volume supports a
96 Furthermore, you should only request the attributes that you need.
97 Some attributes are expensive to calculate on some volume formats.
99 .Dv ATTR_DIR_ENTRYCOUNT
100 is usually expensive to calculate on non-HFS [Plus] volumes.
101 If you don't need a particular attribute, you should not ask for it.
108 parameter must reference a valid file system object.
109 Read, write or execute permission of the object itself is not required, but
110 all directories listed in the path name leading to the object must be
114 .\" attrList parameter
118 parameter is a pointer to an
120 structure, as defined by
123 It determines what attributes are returned by the function.
124 You are responsible for filling out all fields of this structure before calling the function.
126 typedef u_int32_t attrgroup_t;
129 u_short bitmapcount; /* number of attr. bit sets in list */
130 u_int16_t reserved; /* (to maintain 4-byte alignment) */
131 attrgroup_t commonattr; /* common attribute group */
132 attrgroup_t volattr; /* volume attribute group */
133 attrgroup_t dirattr; /* directory attribute group */
134 attrgroup_t fileattr; /* file attribute group */
135 attrgroup_t forkattr; /* fork attribute group */
137 #define ATTR_BIT_MAP_COUNT 5
141 .\" attrlist elements
145 structure are defined as follows.
146 .Bl -tag -width XXXbitmapcount
149 Number of attribute bit sets in the structure.
150 In current systems you must set this to
151 .Dv ATTR_BIT_MAP_COUNT .
155 You must set this to 0.
158 A bit set that specifies the common attributes that you require.
159 Common attributes relate to all types of file system objects.
160 See below for a description of these attributes.
163 A bit set that specifies the volume attributes that you require.
164 Volume attributes relate to volumes (that is, mounted file systems).
165 See below for a description of these attributes.
166 If you request volume attributes,
168 must reference the root of a volume.
169 In addition, you can't request volume attributes if you also request
170 file or directory attributes.
173 A bit set that specifies the directory attributes that you require.
174 See below for a description of these attributes.
177 A bit set that specifies the file attributes that you require.
178 See below for a description of these attributes.
181 A bit set that specifies the fork attributes that you require.
182 Fork attributes relate to the actual data in the file,
183 which can be held in multiple named contiguous ranges, or forks.
184 See below for a description of these attributes.
185 If the FSOPT_ATTR_CMN_EXTENDED option is given, this bit set is reinterpreted
186 as extended common attributes attributes, also described below.
191 Unless otherwise noted in the lists below, attributes are read-only.
192 Attributes labelled as read/write can be set using
196 .\" attrBuf and attrBufSize parameters
202 parameters specify a buffer into which the function places attribute values.
203 The format of this buffer is sufficiently complex that its description
204 requires a separate section (see below).
205 The initial contents of this buffer are ignored.
212 parameter is a bit set that controls the behaviour of
214 The following option bits are defined.
216 .Bl -tag -width FSOPT_PACK_INVAL_ATTRS
221 will not follow a symlink if it occurs as
222 the last component of
225 .It FSOPT_REPORT_FULLSIZE
226 The size of the attributes reported (in the first
228 field in the attribute buffer) will be the size needed to hold all the
229 requested attributes; if not set, only the attributes actually returned
230 will be reported. This allows the caller to determine if any truncation
233 .It FSOPT_PACK_INVAL_ATTRS
234 If this is bit is set, then all requested attributes, even ones that are
235 not supported by the object or file system, will be returned. Default values
236 will be used for the invalid ones. Requires that
237 .Dv ATTR_CMN_RETURNED_ATTRS
240 .It FSOPT_ATTR_CMN_EXTENDED
241 If this is bit is set, then
242 .Dv ATTR_CMN_GEN_COUNT
244 .Dv ATTR_CMN_DOCUMENT_ID
245 can be requested. When this option is used, forkattrs are reinterpreted as a
246 set of extended common attributes.
252 The data returned in the buffer described by
256 is formatted as follows.
262 The first element of the buffer is a
264 that contains the overall length, in bytes, of the attributes returned.
265 This size includes the length field itself.
268 Following the length field is a list of attributes.
269 Each attribute is represented by a field of its type,
270 where the type is given as part of the attribute description (below).
273 The attributes are placed into the attribute buffer in the order
274 that they are described below.
277 Each attribute is aligned to a 4-byte boundary (including 64-bit data types).
281 If the attribute is of variable length, it is represented
284 structure, as defined by
289 typedef struct attrreference {
290 int32_t attr_dataoffset;
291 u_int32_t attr_length;
296 This structure contains a 'pointer' to the variable length attribute data.
299 field is the length of the attribute data (in bytes).
302 field is the offset in bytes from the
305 to the attribute data.
306 This offset will always be a multiple of sizeof(u_int32_t) bytes,
307 so you can safely access common data types without fear of alignment
313 function will silently truncate attribute data if
316 The length field at the front of the attribute list always represents
317 the length of the data actually copied into the attribute buffer.
318 If the data is truncated, there is no easy way to determine the
319 buffer size that's required to get all of the requested attributes.
320 You should always pass an
322 that is large enough to accommodate the known size of the attributes
323 in the attribute list (including the leading length field).
326 Because the returned attributes are simply truncated if the buffer is
327 too small, it's possible for a variable length attribute to reference
328 data beyond the end of the attribute buffer. That is, it's possible
329 for the attribute data to start beyond the end of the attribute buffer
333 .Vt attrreference_t ,
342 ) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is,
354 If this happens you must increase the size of the buffer and call
356 to get an accurate copy of the attribute.
358 .Sh COMMON ATTRIBUTES
360 Common attributes relate to all types of file system objects.
361 The following common attributes are defined.
363 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
365 .It ATTR_CMN_RETURNED_ATTRS
368 structure which is used to report which of the requested attributes
369 were actually returned. This attribute, when requested, will always
370 be the first attribute returned. By default, unsupported attributes
371 will be skipped (i.e. not packed into the output buffer). This behavior
372 can be over-ridden using the FSOPT_PACK_INVAL_ATTRS option flag. Both
373 .Xr getattrlist 2 and
374 .Xr getatttrlistbulk 2 support this attribute while
375 .Xr searchfs 2 does not.
380 structure containing the name of the file system object as
381 UTF-8 encoded, null terminated C string.
382 The attribute data length will not be greater than
384 + 1 characters, which is
386 * 3 + 1 bytes (as one UTF-8-encoded character may
387 take up to three bytes).
393 containing the device number of the device on which this
394 file system object's volume is mounted.
399 structure returned by
405 structure containing the file system identifier for the volume on which
406 the file system object resides.
411 structure returned by
417 that identifies the type of file system object.
418 The values are taken from
426 that identifies the type of file system containing the object.
427 The values are taken from
435 structure that uniquely identifies the file system object within a mounted
436 volume for the duration of it's mount; this identifier is not guaranteed to be
437 persistent for the volume and may change every time the volume is mounted.
438 If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
441 On HFS+ volumes, the ATTR_CMN_OBJID of a file system object is distinct from
442 the ATTR_CMN_OBJID of any hard link to that file system object. Although the
443 ATTR_CMN_OBJID of a file system object may appear similar (in whole
444 or in part) to it's ATTR_CMN_FILEID (see description of ATTR_CMN_FILEID below),
445 \fBno relation between the two attributes should ever be implied.\fP
447 .It ATTR_CMN_OBJPERMANENTID
450 structure that uniquely and persistently identifies the file system object
451 within its volume; persistence implies that this attribute is unaffected by
452 mount/unmount operations on the volume.
453 If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
456 Some file systems can not return this attribute when the volume is mounted
457 read-only and will fail the request with error
460 (e.g. original HFS modifies on disk structures to generate persistent
461 identifiers, and hence cannot do so if the volume is mounted read only.)
463 .It ATTR_CMN_PAROBJID
466 structure that uniquely identifies the parent directory of the file system
467 object within a mounted volume, for the duration of the volume mount; this
468 identifier is not guaranteed to be persistent for the volume and may change
469 every time the volume is mounted.
470 If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
474 If a file system object is hard linked from multiple directories, the parent
475 directory returned for this attribute is non deterministic; it can be any one
476 of the parent directories of this object.
478 For some volume formats the computing cost for this attribute is significant;
479 developers are advised to request this attribute sparingly.
484 containing a text encoding hint for
485 the file system object's name.
486 It is included to facilitate the lossless round trip conversion of names between
487 Unicode and traditional Mac OS script encodings.
488 File systems that do not have an appropriate text encoding value should return
489 kTextEncodingMacUnicode.
494 structure containing the time that the file system object
500 structure containing the time that the file system object
506 structure returned by
512 structure containing the time that the file system object's
513 attributes were last modified.
518 structure returned by
524 structure containing the time that the file system object
530 structure returned by
533 .It ATTR_CMN_BKUPTIME
536 structure containing the time that the file system object was
538 This value is for use by backup utilities.
539 The file system stores but does not interpret the value.
541 .It ATTR_CMN_FNDRINFO
542 (read/write) 32 bytes of data for use by the Finder.
543 Equivalent to the concatenation of a
548 (or, for directories, a
551 .Vt ExtendedFolderInfo
554 This attribute is not byte swapped by the file system.
555 The value of multibyte fields on disk is always big endian.
556 When running on a little endian system (such as Darwin on x86),
557 you must byte swap any multibyte fields.
562 containing the owner of the file system object.
567 structure returned by
573 containing the group of the file system object.
578 structure returned by
581 .It ATTR_CMN_ACCESSMASK
584 containing the access permissions of the file system object.
589 structure returned by
591 Only the permission bits of
593 are valid; other bits should be ignored,
594 e.g., by masking with
600 containing file flags.
605 structure returned by
607 For more information about these flags, see
610 .It ATTR_CMN_GEN_COUNT
613 containing a non zero monotonically increasing generation
614 count for this file system object. The generation count tracks
615 the number of times the data in a file system object has been
616 modified. No meaning can be implied from its value. The
617 value of the generation count for a file system object can
618 be compared against a previous value of the same file system
619 object for equality; i.e. an unchanged generation
620 count indicates identical data. Requesting this attribute requires the
621 FSOPT_ATTR_CMN_EXTENDED option flag.
624 A generation count value of 0 is invalid and cannot be used to
625 determine data change.
627 The generation count is invalid while a file is mmap'ed. An invalid
628 generation count value of 0 will be returned for mmap'ed files.
630 .It ATTR_CMN_DOCUMENT_ID
633 containing the document id. The document id is a value assigned
634 by the kernel to a document (which can be a file or directory)
635 and is used to track the data regardless of where it gets moved.
636 The document id survives safe saves; i.e it is sticky to the path it
637 was assigned to. Requesting this attribute requires the
638 FSOPT_ATTR_CMN_EXTENDED option flag.
640 A document id of 0 is invalid.
642 .It ATTR_CMN_USERACCESS
645 containing the effective permissions of the current user
646 (the calling process's effective UID) for this file system object.
647 You can test for read, write, and execute permission using
657 .It ATTR_CMN_EXTENDED_SECURITY
658 A variable-length object (thus an
660 structure) containing a
662 structure, of which only the ACL entry is used.
667 of the owner of the file system object. Analoguous to
668 .Dv ATTR_CMN_OWNERID .
673 of the group to which the file system object belongs.
680 that uniquely identifies the file system object within it's mounted volume.
685 structure returned by
688 .It ATTR_CMN_PARENTID
691 that identifies the parent directory of the file system object.
693 .It ATTR_CMN_FULLPATH
696 structure containing the full path (resolving all symlinks) to
697 the file system object as
698 a UTF-8 encoded, null terminated C string.
699 The attribute data length will not be greater than
701 Inconsistent behavior may be observed when this attribute is requested on
702 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
703 natively. Callers should be aware of this when requesting the full path of a hard-linked item.
705 .It ATTR_CMN_ADDEDTIME
708 that contains the time that the file system object was created or renamed into
709 its containing directory. Note that inconsistent behavior may be observed
710 when this attribute is requested on hard-linked items.
712 .It ATTR_CMN_DATA_PROTECT_FLAGS
715 that contains the file or directory's data protection class.
720 .Sh VOLUME ATTRIBUTES
722 Volume attributes relate to volumes (that is, mounted file systems).
723 The following volume attributes are defined.
725 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
728 For reasons that are not at all obvious, you must set
732 field if you request any other volume attributes.
733 This does not result in any attribute data being added to the attribute buffer.
738 containing the file system type.
743 structure returned by
745 Generally not a useful value.
747 .It ATTR_VOL_SIGNATURE
750 containing the volume signature word.
751 This value is unique within a given file system type and lets you
752 distinguish between different volume formats handled by the same file system.
757 containing the total size of the volume in bytes.
759 .It ATTR_VOL_SPACEFREE
762 containing the free space on the volume in bytes.
764 .It ATTR_VOL_SPACEAVAIL
767 containing the space, in bytes, on the volume available to non-privileged processes.
768 This is the free space minus the amount of space reserved by the system to prevent critical
769 disk exhaustion errors.
770 Non-privileged programs, like a disk management tool, should use this value to display the
771 space available to the user.
773 .Dv ATTR_VOL_SPACEAVAIL
775 .Dv ATTR_VOL_SPACEFREE
783 .It ATTR_VOL_MINALLOCATION
786 containing the minimum allocation size on the volume in bytes.
787 If you create a file containing one byte, it will consume this much space.
789 .It ATTR_VOL_ALLOCATIONCLUMP
792 containing the allocation clump size on the volume, in bytes.
793 As a file is extended, the file system will attempt to allocate
794 this much space each time in order to reduce fragmentation.
796 .It ATTR_VOL_IOBLOCKSIZE
799 containing the optimal block size when reading or writing data.
804 structure returned by
807 .It ATTR_VOL_OBJCOUNT
810 containing the number of file system objects on the volume.
812 .It ATTR_VOL_FILECOUNT
815 containing the number of files on the volume.
817 .It ATTR_VOL_DIRCOUNT
820 containing the number of directories on the volume.
822 .It ATTR_VOL_MAXOBJCOUNT
825 containing the maximum number of file system objects that can be stored on the volume.
827 .It ATTR_VOL_MOUNTPOINT
830 structure containing the path to the volume's mount point as a
831 UTF-8 encoded, null terminated C string.
832 The attribute data length will not be greater than
838 structure returned by
844 structure containing the name of the volume as a
845 UTF-8 encoded, null terminated C string.
846 The attribute data length will not be greater than
851 This attribute is only read/write if the
852 .Dv VOL_CAP_INT_VOL_RENAME
853 bit is set in the volume capabilities (see below).
856 .It ATTR_VOL_MOUNTFLAGS
859 containing the volume mount flags.
860 This is a copy of the value passed to the
864 when the volume was mounted.
869 structure returned by
872 .It ATTR_VOL_MOUNTEDDEVICE
875 structure that returns the same value as the
879 structure returned by
881 For local volumes this is the path to the device on which the volume is mounted as a
882 UTF-8 encoded, null terminated C string.
883 For network volumes, this is a unique string that identifies the mount.
884 The attribute data length will not be greater than
888 .It ATTR_VOL_ENCODINGSUSED
890 .Vt unsigned long long
891 containing a bitmap of the text encodings used on this volume.
892 For more information about this, see the discussion of
894 in DTS Technote 1150 "HFS Plus Volume Format".
896 .It ATTR_VOL_CAPABILITIES
898 .Vt vol_capabilities_attr_t
899 structure describing the optional features supported by this volume.
900 See below for a discussion of volume capabilities.
905 containing the file system UUID. Typically this will be a
908 .It ATTR_VOL_QUOTA_SIZE
911 containing the maximum size of the volume in bytes.
913 .It ATTR_VOL_RESERVED_SIZE
916 containing the minimum size of the volume in bytes.
918 .It ATTR_VOL_ATTRIBUTES
920 .Vt vol_attributes_attr_t
921 structure describing the attributes supported by this volume.
922 This structure is discussed below, along with volume capabilities.
926 .Sh DIRECTORY ATTRIBUTES
928 The following directory attributes are defined.
930 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
932 .It ATTR_DIR_LINKCOUNT
935 containing the number of hard links to the directory;
936 this does not include the historical "." and ".." entries.
937 For file systems that do not support hard links to directories,
938 this value will be 1.
940 .It ATTR_DIR_ENTRYCOUNT
943 containing the number of file system objects in the directory, not including
944 any synthetic items. The historical "." and ".." entries are also
945 excluded from this count.
947 .It ATTR_DIR_MOUNTSTATUS
950 containing flags describing what's mounted on the directory.
951 Currently the only flag defined is
952 .Dv DIR_MNTSTATUS_MNTPOINT,
953 which indicates that there is a file system mounted on this directory.
955 .It ATTR_DIR_ALLOCSIZE
958 containing the number of bytes on disk used by the directory
961 .It ATTR_DIR_IOBLOCKSIZE
964 containing the optimal block size when reading or writing data.
966 .It ATTR_DIR_DATALENGTH
969 containing the length of the directory in bytes (the logical size).
973 Requested directory attributes are not returned for file system objects that
978 The following file attributes are defined.
980 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
982 .It ATTR_FILE_LINKCOUNT
985 containing the number of hard links to this file.
990 structure returned by
993 .It ATTR_FILE_TOTALSIZE
996 containing the total number of bytes in all forks of the file (the logical size).
998 .It ATTR_FILE_ALLOCSIZE
1001 containing a count of the bytes on disk used by all of the file's forks (the physical size).
1003 .It ATTR_FILE_IOBLOCKSIZE
1006 containing the optimal block size when reading or writing this file's data.
1008 .It ATTR_FILE_CLUMPSIZE
1011 containing the allocation clump size for this file, in bytes.
1012 As the file is extended, the file system will attempt to allocate
1013 this much space each time in order to reduce fragmentation.
1014 This value applies to the data fork.
1016 .It ATTR_FILE_DEVTYPE
1019 containing the device type for a special device file.
1024 structure returned by
1027 .It ATTR_FILE_FILETYPE
1030 that whose value is reserved.
1031 Clients should ignore its value.
1032 New volume format implementations should not support this attribute.
1034 .It ATTR_FILE_FORKCOUNT
1037 containing the number of forks in the file.
1038 No built-in file systems on Mac OS X currently support forks other
1039 than the data and resource fork.
1041 .It ATTR_FILE_FORKLIST
1044 structure containing a list of named forks of the file.
1045 No built-in file systems on Mac OS X currently support forks
1046 other than the data and resource fork.
1047 Because of this, the structure of this attribute's value is not yet defined.
1049 .It ATTR_FILE_DATALENGTH
1052 containing the length of the data fork in bytes (the logical size).
1054 .It ATTR_FILE_DATAALLOCSIZE
1057 containing a count of the bytes on disk used by the data fork (the physical size).
1059 .It ATTR_FILE_DATAEXTENTS
1062 array for the data fork.
1063 The array contains eight
1065 structures which represent the first
1066 eight extents of the fork.
1068 This attributes exists for compatibility reasons.
1069 New clients should not use this attribute.
1070 Rather, they should use the
1076 In current implementations the value may not be entirely accurate for
1077 a variety of reasons.
1079 .It ATTR_FILE_RSRCLENGTH
1082 containing the length of the resource fork in bytes (the logical size).
1084 .It ATTR_FILE_RSRCALLOCSIZE
1087 containing a count of the bytes on disk used by the resource fork (the physical size).
1089 .It ATTR_FILE_RSRCEXTENTS
1092 array for the resource fork.
1093 The array contains eight
1095 structures which represent the first
1096 eight extents of the fork.
1099 .Dv ATTR_FILE_DATAEXTENTS .
1104 File attributes are used for any file system object that is not a directory,
1105 not just ordinary files.
1106 Requested file attributes are not returned for file system objects that
1111 Fork attributes relate to the actual data in the file,
1112 which can be held in multiple named contiguous ranges, or forks.
1113 These cannot be used if the FSOPT_ATTR_CMN_EXTENDED is given.
1114 The following fork attributes are defined.
1116 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
1118 .It ATTR_FORK_TOTALSIZE
1122 containing the length of the fork in bytes (the logical size).
1124 .It ATTR_FORK_ALLOCSIZE
1128 containing a count of the bytes on disk used by the fork (the physical size).
1130 .It ATTR_FORK_RESERVED
1132 You must set this to 0.
1137 Fork attributes are deprecated and all bits are reserved.
1138 They are not properly implemented by any current Mac OS X
1139 volume format implementation.
1140 We strongly recommend that client programs do not request fork attributes.
1141 If you are implementing a volume format, you should not support these attributes.
1143 .Sh COMMON EXTENDED ATTRIBUTES
1145 Common extended attributes are like common attributes except that they are set
1146 in the forkattr field and can only be used if the FSOPT_ATTR_CMN_EXTENDED
1147 option is given. Use of these attributes is mutually exclusive with the above
1150 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
1152 .It ATTR_CMNEXT_RELPATH
1155 structure containing the mount-relative path of
1156 the file system object as
1157 a UTF-8 encoded, null terminated C string.
1158 The attribute data length will not be greater than
1160 Inconsistent behavior may be observed when this attribute is requested on
1161 hard-linked items, particularly when the file system does not support
1162 ATTR_CMN_PARENTID natively. Callers should be aware of this when requesting the
1163 relative path of a hard-linked item.
1165 .It ATTR_CMNEXT_PRIVATESIZE
1168 containing the number of bytes that are \fBnot\fP trapped inside a clone
1169 or snapshot, and which would be freed immediately if the file were deleted.
1173 .Sh VOLUME CAPABILITIES
1175 .\" vol_capabilities_attr_t
1177 Not all volumes support all features.
1179 .Dv ATTR_VOL_CAPABILITIES
1181 .Vt vol_capabilities_attr_t
1182 structure (shown below) that indicates which features are supported by the volume.
1185 typedef u_int32_t vol_capabilities_set_t[4];
1188 #define VOL_CAPABILITIES_FORMAT 0
1189 #define VOL_CAPABILITIES_INTERFACES 1
1190 #define VOL_CAPABILITIES_RESERVED1 2
1191 #define VOL_CAPABILITIES_RESERVED2 3
1194 typedef struct vol_capabilities_attr {
1195 vol_capabilities_set_t capabilities;
1196 vol_capabilities_set_t valid;
1197 } vol_capabilities_attr_t;
1201 The structure contains two fields,
1205 Each consists of an array of four elements.
1206 The arrays are indexed by the following values.
1208 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1210 .It VOL_CAPABILITIES_FORMAT
1211 This element contains information about the volume format.
1213 .Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
1216 .It VOL_CAPABILITIES_INTERFACES
1217 This element contains information about which optional functions are
1218 supported by the volume format implementation.
1220 .Dv VOL_CAP_INT_SEARCHFS
1223 .It VOL_CAPABILITIES_RESERVED1
1225 A file system implementation should set this element to zero.
1226 A client program should ignore this element.
1228 .It VOL_CAPABILITIES_RESERVED2
1230 A file system implementation should set this element to zero.
1231 A client program should ignore this element.
1238 field contains bit sets that indicate which flags are known to the volume format
1240 Each bit indicates whether the contents of the corresponding bit in the
1247 field contains bit sets that indicate whether a particular feature is implemented
1248 by this volume format.
1251 The following bits are defined in the first element (indexed by
1252 .Dv VOL_CAPABILITIES_FORMAT )
1258 .Vt vol_capabilities_attr_t
1261 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1263 .It VOL_CAP_FMT_PERSISTENTOBJECTIDS
1264 If this bit is set the volume format supports persistent object identifiers
1265 and can look up file system objects by their IDs.
1267 .Dv ATTR_CMN_OBJPERMANENTID
1268 for details about how to obtain these identifiers.
1270 .It VOL_CAP_FMT_SYMBOLICLINKS
1271 If this bit is set the volume format supports symbolic links.
1273 .It VOL_CAP_FMT_HARDLINKS
1274 If this bit is set the volume format supports hard links.
1276 .It VOL_CAP_FMT_JOURNAL
1277 If this bit is set the volume format supports a journal used to
1278 speed recovery in case of unplanned restart (such as a power outage
1280 This does not necessarily mean the volume is actively using a journal.
1282 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1284 .It VOL_CAP_FMT_JOURNAL_ACTIVE
1285 If this bit is set the volume is currently using a journal for
1286 speedy recovery after an unplanned restart.
1287 This bit can be set only if
1288 .Dv VOL_CAP_FMT_JOURNAL
1291 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1293 .It VOL_CAP_FMT_NO_ROOT_TIMES
1294 If this bit is set the volume format does not store reliable times for
1295 the root directory, so you should not depend on them to detect changes,
1296 identify volumes across unmount/mount, and so on.
1298 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1300 .It VOL_CAP_FMT_SPARSE_FILES
1301 If this bit is set the volume format supports sparse files,
1302 that is, files which can have 'holes' that have never been written
1303 to, and thus do not consume space on disk.
1304 A sparse file may have an allocated size on disk that is less than its logical length (that is,
1305 .Dv ATTR_FILE_ALLOCSIZE
1307 .Dv ATTR_FILE_TOTALSIZE ).
1310 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1312 .It VOL_CAP_FMT_ZERO_RUNS
1313 For security reasons, parts of a file (runs) that have never been
1314 written to must appear to contain zeroes.
1315 When this bit is set, the volume keeps track of allocated but unwritten
1316 runs of a file so that it can substitute zeroes without actually
1317 writing zeroes to the media.
1318 This provides performance similar to sparse files, but not the space savings.
1320 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1322 .It VOL_CAP_FMT_CASE_SENSITIVE
1323 If this bit is set the volume format treats upper and lower case
1324 characters in file and directory names as different.
1325 Otherwise an upper case character is equivalent to a lower case character,
1326 and you can't have two names that differ solely in the case of
1329 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1331 .It VOL_CAP_FMT_CASE_PRESERVING
1332 If this bit is set the volume format preserves the case of
1333 file and directory names.
1334 Otherwise the volume may change the case of some characters
1335 (typically making them all upper or all lower case).
1337 .Dv VOL_CAP_FMT_CASE_SENSITIVE
1339 .Dv VOL_CAP_FMT_CASE_PRESERVING .
1341 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1343 .It VOL_CAP_FMT_FAST_STATFS
1344 This bit is used as a hint to upper layers to
1347 is fast enough that its results need not be cached by the caller.
1348 A volume format implementation that caches the
1350 information in memory should set this bit.
1351 An implementation that must always read from disk or always perform a network
1352 transaction to satisfy
1354 should not set this bit.
1356 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1358 .It VOL_CAP_FMT_2TB_FILESIZE
1359 If this bit is set the volume format supports file sizes larger
1360 than 4GB, and potentially up to 2TB; it does not indicate
1361 whether the file system supports files larger than that.
1363 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1365 .It VOL_CAP_FMT_OPENDENYMODES
1366 If this bit is set, the volume format supports open deny modes
1367 (e.g., "open for read write, deny write").
1369 .It VOL_CAP_FMT_HIDDEN_FILES
1370 If this bit is set, the volume format supports the
1374 flag is mapped to that volume's native "hidden" or "invisible"
1375 bit (e.g., the invisible bit from the Finder Info extended attribute).
1377 .It VOL_CAP_FMT_PATH_FROM_ID
1378 If this bit is set, the volume format supports the ability to derive a pathname
1379 to the root of the file system given only the ID of an object. This also
1380 implies that object IDs on this file system are persistent and not recycled.
1381 Most file systems will not support this capability.
1383 .It VOL_CAP_FMT_NO_VOLUME_SIZES
1384 If this bit is set the volume format does not support
1385 determining values for total data blocks, available blocks, or free blocks, as in
1394 Historically, those values were set to 0xFFFFFFFF for volumes
1395 that did not support them.
1397 Introduced with Darwin 10.0 (Mac OS X version 10.6).
1399 .It VOL_CAP_FMT_64BIT_OBJECT_IDS
1400 If this bit is set, the volume format uses object IDs that are 64-bit.
1401 This means that ATTR_CMN_FILEID and ATTR_CMN_PARENTID are the primary means of
1402 obtaining object IDs from this volume. The values returned by ATTR_CMN_OBJID,
1403 ATTR_CMN_OBJPERMANENTID, and ATTR_CMN_PAROBJID can be interpreted as 64-bit
1404 object IDs instead of fsobj_id_t.
1406 .It VOL_CAP_FMT_NO_IMMUTABLE_FILES
1407 If this bit is set, the volume format does not support setting the UF_IMMUTABLE
1409 See ATTR_CMN_FLAGS for more details.
1410 .It VOL_CAP_FMT_NO_PERMISSIONS
1411 If this bit is set, the volume format does not support setting file
1413 See ATTR_CMN_USERACCESS for more details.
1418 The following bits are defined in the second element (indexed by
1419 .Dv VOL_CAPABILITIES_INTERFACES )
1425 .Vt vol_capabilities_attr_t
1428 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1430 .It VOL_CAP_INT_SEARCHFS
1431 If this bit is set the volume format implementation supports
1434 .It VOL_CAP_INT_ATTRLIST
1435 If this bit is set the volume format implementation supports
1440 .It VOL_CAP_INT_NFSEXPORT
1441 If this bit is set the volume format implementation allows this volume to be exported via NFS.
1443 .It VOL_CAP_INT_READDIRATTR
1444 If this bit is set the volume format implementation supports
1445 .Xr getdirentriesattr 2 .
1447 .It VOL_CAP_INT_EXCHANGEDATA
1448 If this bit is set the volume format implementation supports
1449 .Xr exchangedata 2 .
1451 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1453 .It VOL_CAP_INT_COPYFILE
1454 If this bit is set the volume format implementation supports the (private and undocumented)
1455 copyfile() function.
1460 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1462 .It VOL_CAP_INT_ALLOCATE
1463 If this bit is set the volume format implementation supports the
1468 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1470 .It VOL_CAP_INT_VOL_RENAME
1471 If this bit is set the volume format implementation allows you to
1472 modify the volume name using
1475 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1477 .It VOL_CAP_INT_ADVLOCK
1478 If this bit is set the volume format implementation supports
1479 advisory locking, that is, the
1487 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1489 .It VOL_CAP_INT_FLOCK
1490 If this bit is set the volume format implementation supports
1501 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1503 .It VOL_CAP_INT_EXTENDED_SECURITY
1504 If this bit is set the volume format implementation supports
1505 extended security controls (ACLs).
1507 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1509 .It VOL_CAP_INT_USERACCESS
1510 If this bit is set the volume format implementation supports the
1511 ATTR_CMN_USERACCESS attribute.
1513 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1515 .It VOL_CAP_INT_MANLOCK
1516 If this bit is set, the volume format implementation supports
1517 AFP-style mandatory byte range locks via
1520 .It VOL_CAP_INT_EXTENDED_ATTR
1521 If this bit is set, the volume format implementation supports
1522 native extended attributes (see
1523 .Xr setxattr 2 Ns ).
1525 .It VOL_CAP_INT_CLONE
1526 If this bit is set, the file system supports cloning files and directories.
1531 .It VOL_CAP_INT_NAMEDSTREAMS
1532 If this bit is set, the volume format implementation supports
1533 native named streams.
1535 .It VOL_CAP_INT_RENAME_SWAP
1536 If this bit is set, the file system supports swapping file system
1541 .It VOL_CAP_INT_RENAME_EXCL
1542 If this bit is set, the file system supports an exclusive rename
1550 .\" vol_attributes_attr_t
1552 A volume can also report which attributes it supports.
1553 This information is returned by the
1554 .Dv ATTR_VOL_ATTRIBUTES
1555 attribute, which returns a
1556 .Vt vol_attributes_attr_t
1557 structure (shown below).
1560 typedef struct attribute_set {
1561 attrgroup_t commonattr; /* common attribute group */
1562 attrgroup_t volattr; /* volume attribute group */
1563 attrgroup_t dirattr; /* directory attribute group */
1564 attrgroup_t fileattr; /* file attribute group */
1565 attrgroup_t forkattr; /* fork attribute group */
1569 typedef struct vol_attributes_attr {
1570 attribute_set_t validattr;
1571 attribute_set_t nativeattr;
1572 } vol_attributes_attr_t;
1578 field consists of a number of bit sets that indicate whether an attribute is
1579 supported by the volume format implementation.
1582 is similar except that the bit sets indicate whether an attribute is supported
1583 natively by the volume format.
1584 An attribute is supported natively if the volume format implementation does not have to do
1585 any complex conversions to access the attribute.
1586 For example, a volume format might support persistent object identifiers, but
1587 doing so requires a complex table lookup that is not part of the core volume
1590 .Dv ATTR_VOL_ATTRIBUTES
1591 attribute would return
1592 .Dv ATTR_CMN_OBJPERMANENTID
1596 .Vt vol_attributes_attr_t ,
1602 Upon successful completion a value of 0 is returned.
1603 Otherwise, a value of -1 is returned and
1605 is set to indicate the error.
1608 Not all volumes support
1610 The best way to test whether a volume supports this function is to
1611 simply call it and check the error result.
1615 if it is not supported on a particular volume.
1620 function has been undocumented for more than two years.
1621 In that time a number of volume format implementations have been created without
1622 a proper specification for the behaviour of this routine.
1623 You may encounter volume format implementations with slightly different
1624 behaviour than what is described here.
1625 Your program is expected to be tolerant of this variant behaviour.
1628 If you're implementing a volume format that supports
1630 you should be careful to support the behaviour specified by this document.
1640 The volume does not support the query.
1643 A component of the path prefix for
1647 .It Bq Er ENAMETOOLONG
1648 A component of a path name for
1652 characters, or an entire path name exceeded
1657 The file system object for
1662 The file descriptor argument for
1664 is not a valid file descriptor.
1667 Search permission is denied for a component of the path prefix for
1671 Too many symbolic links were encountered in translating the pathname
1680 points to an invalid address.
1688 .Dv ATTR_BIT_MAP_COUNT .
1691 You requested an invalid attribute.
1694 You requested an attribute that is not supported for this file system object.
1697 You requested volume attributes and directory or file attributes.
1700 You requested volume attributes but
1702 does not reference the root of the volume.
1705 The volume is read-only but must be modified in order to return this attribute.
1708 An I/O error occurred while reading from or writing to the file system.
1711 In addition to the errors returned by the
1715 function may fail if:
1720 argument does not specify an absolute path and the
1724 nor a valid file descriptor open for searching.
1728 argument is not an absolute path and
1732 nor a file descriptor associated with a directory.
1738 If you request any volume attributes, you must set
1742 field, even though it generates no result in the attribute buffer.
1745 The order that attributes are stored in the attribute buffer almost
1746 invariably matches the order of attribute mask bit values.
1749 (0x00000001) comes before
1751 (0x00000002) because its value is smaller.
1752 When ordering attributes, you should always use the order in which they
1753 are described above.
1758 structure is 64-bits (two 32-bit elements) in 32-bit code, and
1759 128-bits (two 64-bit elements) in 64-bit code; however, it is aligned
1760 on a 4-byte (32-bit) boundary, even in 64-bit code.
1762 If you use a structure
1763 for the attribute data, it must be correctly packed and aligned (see
1767 Inconsistent behavior may be observed when the ATTR_CMN_FULLPATH attribute is requested on
1768 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
1769 natively. Callers should be aware of this when requesting the full path of a hard-linked item, especially
1770 if the full path crosses mount points.
1773 For more caveats, see also the compatibility notes above.
1777 The following code prints the file type and creator of a file,
1778 assuming that the volume supports the required attributes.
1784 #include <sys/attr.h>
1785 #include <sys/errno.h>
1787 #include <sys/vnode.h>
1790 typedef struct attrlist attrlist_t;
1793 struct FInfoAttrBuf {
1795 fsobj_type_t objType;
1796 char finderInfo[32];
1797 } __attribute__((aligned(4), packed));
1798 typedef struct FInfoAttrBuf FInfoAttrBuf;
1801 static int FInfoDemo(const char *path)
1804 attrlist_t attrList;
1805 FInfoAttrBuf attrBuf;
1808 memset(&attrList, 0, sizeof(attrList));
1809 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1810 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1813 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1820 assert(attrBuf.length == sizeof(attrBuf));
1823 printf("Finder information for %s:\en", path);
1824 switch (attrBuf.objType) {
1826 printf("file type = '%.4s'\en", &attrBuf.finderInfo[0]);
1827 printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
1830 printf("directory\en");
1833 printf("other object type, %d\en", attrBuf.objType);
1844 The following code is an alternative implementation that uses nested structures
1845 to group the related attributes.
1852 #include <sys/attr.h>
1853 #include <sys/errno.h>
1855 #include <sys/vnode.h>
1858 typedef struct attrlist attrlist_t;
1861 struct FInfo2CommonAttrBuf {
1862 fsobj_type_t objType;
1863 char finderInfo[32];
1864 } __attribute__((aligned(4), packed));
1865 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
1868 struct FInfo2AttrBuf {
1870 FInfo2CommonAttrBuf common;
1871 } __attribute__((aligned(4), packed));;
1872 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
1875 static int FInfo2Demo(const char *path)
1878 attrlist_t attrList;
1879 FInfo2AttrBuf attrBuf;
1882 memset(&attrList, 0, sizeof(attrList));
1883 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1884 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1887 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1894 assert(attrBuf.length == sizeof(attrBuf));
1897 printf("Finder information for %s:\en", path);
1898 switch (attrBuf.common.objType) {
1901 "file type = '%.4s'\en",
1902 &attrBuf.common.finderInfo[0]
1905 "file creator = '%.4s'\en",
1906 &attrBuf.common.finderInfo[4]
1910 printf("directory\en");
1914 "other object type, %d\en",
1915 attrBuf.common.objType
1927 The following example shows how to deal with variable length attributes.
1928 It assumes that the volume specified by
1930 supports the necessary attributes.
1937 #include <sys/attr.h>
1938 #include <sys/errno.h>
1940 #include <sys/vnode.h>
1943 typedef struct attrlist attrlist_t;
1948 u_int32_t fileCount;
1950 attrreference_t mountPointRef;
1951 attrreference_t volNameRef;
1952 char mountPointSpace[MAXPATHLEN];
1953 char volNameSpace[MAXPATHLEN];
1954 } __attribute__((aligned(4), packed));
1955 typedef struct VolAttrBuf VolAttrBuf;
1958 static int VolDemo(const char *path)
1961 attrlist_t attrList;
1965 memset(&attrList, 0, sizeof(attrList));
1966 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1967 attrList.volattr = ATTR_VOL_INFO
1968 | ATTR_VOL_FILECOUNT
1970 | ATTR_VOL_MOUNTPOINT
1974 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1981 assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace));
1982 assert(attrBuf.length <= sizeof(attrBuf));
1985 printf("Volume information for %s:\en", path);
1986 printf("ATTR_VOL_FILECOUNT: %u\en", attrBuf.fileCount);
1987 printf("ATTR_VOL_DIRCOUNT: %u\en", attrBuf.dirCount);
1989 "ATTR_VOL_MOUNTPOINT: %.*s\en",
1990 (int) attrBuf.mountPointRef.attr_length,
1991 ( ((char *) &attrBuf.mountPointRef)
1992 + attrBuf.mountPointRef.attr_dataoffset )
1995 "ATTR_VOL_NAME: %.*s\en",
1996 (int) attrBuf.volNameRef.attr_length,
1997 ( ((char *) &attrBuf.volNameRef)
1998 + attrBuf.volNameRef.attr_dataoffset )
2007 The following sample demonstrates the need to use packing and alignment
2008 controls; without the attribute, in 64-bit code, the fields of the structure are not
2009 placed at the locations that the kernel expects.
2018 #include <sys/attr.h>
2020 /* The alignment and packing attribute is necessary in 64-bit code */
2021 struct AttrListTimes {
2023 struct timespec st_crtime;
2024 struct timespec st_modtime;
2025 } __attribute__((aligned(4), packed));
2027 main(int argc, char **argv)
2032 for (i = 1; i < argc; i++) {
2033 struct attrlist attrList;
2034 struct AttrListTimes myStat = {0};
2035 char *path = argv[i];
2037 memset(&attrList, 0, sizeof(attrList));
2038 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
2039 attrList.commonattr = ATTR_CMN_CRTIME |
2042 rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);
2045 warn("getattrlist(%s)", path);
2048 printf("%s: Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
2059 .Xr exchangedata 2 ,
2061 .Xr getattrlistbulk 2 ,
2071 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
2074 function call appeared in OS X 10.10 .
projects / apple / xnu.git / blob