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.
189 Unless otherwise noted in the lists below, attributes are read-only.
190 Attributes labelled as read/write can be set using
194 .\" attrBuf and attrBufSize parameters
200 parameters specify a buffer into which the function places attribute values.
201 The format of this buffer is sufficiently complex that its description
202 requires a separate section (see below).
203 The initial contents of this buffer are ignored.
210 parameter is a bit set that controls the behaviour of
212 The following option bits are defined.
214 .Bl -tag -width FSOPT_PACK_INVAL_ATTRS
219 will not follow a symlink if it occurs as
220 the last component of
223 .It FSOPT_REPORT_FULLSIZE
224 The size of the attributes reported (in the first
226 field in the attribute buffer) will be the size needed to hold all the
227 requested attributes; if not set, only the attributes actually returned
228 will be reported. This allows the caller to determine if any truncation
231 .It FSOPT_PACK_INVAL_ATTRS
232 If this is bit is set, then all requested attributes, even ones that are
233 not supported by the object or file system, will be returned. Default values
234 will be used for the invalid ones. Requires that
235 .Dv ATTR_CMN_RETURNED_ATTRS
238 .It FSOPT_ATTR_CMN_EXTENDED
239 If this is bit is set, then
240 .Dv ATTR_CMN_GEN_COUNT
242 .Dv ATTR_CMN_DOCUMENT_ID
243 can be requested. When this option is used, callers must not reference
250 The data returned in the buffer described by
254 is formatted as follows.
260 The first element of the buffer is a
262 that contains the overall length, in bytes, of the attributes returned.
263 This size includes the length field itself.
266 Following the length field is a list of attributes.
267 Each attribute is represented by a field of its type,
268 where the type is given as part of the attribute description (below).
271 The attributes are placed into the attribute buffer in the order
272 that they are described below.
275 Each attribute is aligned to a 4-byte boundary (including 64-bit data types).
279 If the attribute is of variable length, it is represented
282 structure, as defined by
287 typedef struct attrreference {
288 int32_t attr_dataoffset;
289 u_int32_t attr_length;
294 This structure contains a 'pointer' to the variable length attribute data.
297 field is the length of the attribute data (in bytes).
300 field is the offset in bytes from the
303 to the attribute data.
304 This offset will always be a multiple of sizeof(u_int32_t) bytes,
305 so you can safely access common data types without fear of alignment
311 function will silently truncate attribute data if
314 The length field at the front of the attribute list always represents
315 the length of the data actually copied into the attribute buffer.
316 If the data is truncated, there is no easy way to determine the
317 buffer size that's required to get all of the requested attributes.
318 You should always pass an
320 that is large enough to accommodate the known size of the attributes
321 in the attribute list (including the leading length field).
324 Because the returned attributes are simply truncated if the buffer is
325 too small, it's possible for a variable length attribute to reference
326 data beyond the end of the attribute buffer. That is, it's possible
327 for the attribute data to start beyond the end of the attribute buffer
331 .Vt attrreference_t ,
340 ) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is,
352 If this happens you must increase the size of the buffer and call
354 to get an accurate copy of the attribute.
356 .Sh COMMON ATTRIBUTES
358 Common attributes relate to all types of file system objects.
359 The following common attributes are defined.
361 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
363 .It ATTR_CMN_RETURNED_ATTRS
366 structure which is used to report which of the requested attributes
367 were actually returned. This attribute, when requested, will always
368 be the first attribute returned. By default, unsupported attributes
369 will be skipped (i.e. not packed into the output buffer). This behavior
370 can be over-ridden using the FSOPT_PACK_INVAL_ATTRS option flag. Both
371 .Xr getattrlist 2 and
372 .Xr getatttrlistbulk 2 support this attribute while
373 .Xr searchfs 2 does not.
378 structure containing the name of the file system object as
379 UTF-8 encoded, null terminated C string.
380 The attribute data length will not be greater than
382 + 1 characters, which is
384 * 3 + 1 bytes (as one UTF-8-encoded character may
385 take up to three bytes).
391 containing the device number of the device on which this
392 file system object's volume is mounted.
397 structure returned by
403 structure containing the file system identifier for the volume on which
404 the file system object resides.
409 structure returned by
415 that identifies the type of file system object.
416 The values are taken from
424 that identifies the type of file system containing the object.
425 The values are taken from
433 structure that uniquely identifies the file system object within a mounted
434 volume for the duration of it's mount; this identifier is not guaranteed to be
435 persistent for the volume and may change every time the volume is mounted.
436 If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
439 On HFS+ volumes, the ATTR_CMN_OBJID of a file system object is distinct from
440 the ATTR_CMN_OBJID of any hard link to that file system object. Although the
441 ATTR_CMN_OBJID of a file system object may appear similar (in whole
442 or in part) to it's ATTR_CMN_FILEID (see description of ATTR_CMN_FILEID below),
443 \fBno relation between the two attributes should ever be implied.\fP
445 .It ATTR_CMN_OBJPERMANENTID
448 structure that uniquely and persistently identifies the file system object
449 within its volume; persistence implies that this attribute is unaffected by
450 mount/unmount operations on the volume.
451 If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
454 Some file systems can not return this attribute when the volume is mounted
455 read-only and will fail the request with error
458 (e.g. original HFS modifies on disk structures to generate persistent
459 identifiers, and hence cannot do so if the volume is mounted read only.)
461 .It ATTR_CMN_PAROBJID
464 structure that uniquely identifies the parent directory of the file system
465 object within a mounted volume, for the duration of the volume mount; this
466 identifier is not guaranteed to be persistent for the volume and may change
467 every time the volume is mounted.
468 If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
472 If a file system object is hard linked from multiple directories, the parent
473 directory returned for this attribute is non deterministic; it can be any one
474 of the parent directories of this object.
476 For some volume formats the computing cost for this attribute is significant;
477 developers are advised to request this attribute sparingly.
482 containing a text encoding hint for
483 the file system object's name.
484 It is included to facilitate the lossless round trip conversion of names between
485 Unicode and traditional Mac OS script encodings.
486 File systems that do not have an appropriate text encoding value should return
487 kTextEncodingMacUnicode.
492 structure containing the time that the file system object
498 structure containing the time that the file system object
504 structure returned by
510 structure containing the time that the file system object's
511 attributes were last modified.
516 structure returned by
522 structure containing the time that the file system object
528 structure returned by
531 .It ATTR_CMN_BKUPTIME
534 structure containing the time that the file system object was
536 This value is for use by backup utilities.
537 The file system stores but does not interpret the value.
539 .It ATTR_CMN_FNDRINFO
540 (read/write) 32 bytes of data for use by the Finder.
541 Equivalent to the concatenation of a
546 (or, for directories, a
549 .Vt ExtendedFolderInfo
552 This attribute is not byte swapped by the file system.
553 The value of multibyte fields on disk is always big endian.
554 When running on a little endian system (such as Darwin on x86),
555 you must byte swap any multibyte fields.
560 containing the owner of the file system object.
565 structure returned by
571 containing the group of the file system object.
576 structure returned by
579 .It ATTR_CMN_ACCESSMASK
582 containing the access permissions of the file system object.
587 structure returned by
589 Only the permission bits of
591 are valid; other bits should be ignored,
592 e.g., by masking with
598 containing file flags.
603 structure returned by
605 For more information about these flags, see
608 .It ATTR_CMN_GEN_COUNT
611 containing a non zero monotonically increasing generation
612 count for this file system object. The generation count tracks
613 the number of times the data in a file system object has been
614 modified. No meaning can be implied from its value. The
615 value of the generation count for a file system object can
616 be compared against a previous value of the same file system
617 object for equality; i.e. an unchanged generation
618 count indicates identical data. Requesting this attribute requires the
619 FSOPT_ATTR_CMN_EXTENDED option flag.
622 A generation count value of 0 is invalid and cannot be used to
623 determine data change.
625 The generation count is invalid while a file is mmap'ed. An invalid
626 generation count value of 0 will be returned for mmap'ed files.
628 .It ATTR_CMN_DOCUMENT_ID
631 containing the document id. The document id is a value assigned
632 by the kernel to a document (which can be a file or directory)
633 and is used to track the data regardless of where it gets moved.
634 The document id survives safe saves; i.e it is sticky to the path it
635 was assigned to. Requesting this attribute requires the
636 FSOPT_ATTR_CMN_EXTENDED option flag.
638 A document id of 0 is invalid.
640 .It ATTR_CMN_USERACCESS
643 containing the effective permissions of the current user
644 (the calling process's effective UID) for this file system object.
645 You can test for read, write, and execute permission using
655 .It ATTR_CMN_EXTENDED_SECURITY
656 A variable-length object (thus an
658 structure) containing a
660 structure, of which only the ACL entry is used.
665 of the owner of the file system object. Analoguous to
666 .Dv ATTR_CMN_OWNERID .
671 of the group to which the file system object belongs.
678 that uniquely identifies the file system object within it's mounted volume.
683 structure returned by
686 .It ATTR_CMN_PARENTID
689 that identifies the parent directory of the file system object.
691 .It ATTR_CMN_FULLPATH
694 structure containing the full path (resolving all symlinks) to
695 the file system object as
696 a UTF-8 encoded, null terminated C string.
697 The attribute data length will not be greater than
699 Inconsistent behavior may be observed when this attribute is requested on
700 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
701 natively. Callers should be aware of this when requesting the full path of a hard-linked item.
703 .It ATTR_CMN_ADDEDTIME
706 that contains the time that the file system object was created or renamed into
707 its containing directory. Note that inconsistent behavior may be observed
708 when this attribute is requested on hard-linked items.
710 .It ATTR_CMN_DATA_PROTECT_FLAGS
713 that contains the file or directory's data protection class.
718 .Sh VOLUME ATTRIBUTES
720 Volume attributes relate to volumes (that is, mounted file systems).
721 The following volume attributes are defined.
723 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
726 For reasons that are not at all obvious, you must set
730 field if you request any other volume attributes.
731 This does not result in any attribute data being added to the attribute buffer.
736 containing the file system type.
741 structure returned by
743 Generally not a useful value.
745 .It ATTR_VOL_SIGNATURE
748 containing the volume signature word.
749 This value is unique within a given file system type and lets you
750 distinguish between different volume formats handled by the same file system.
755 containing the total size of the volume in bytes.
757 .It ATTR_VOL_SPACEFREE
760 containing the free space on the volume in bytes.
762 .It ATTR_VOL_SPACEAVAIL
765 containing the space, in bytes, on the volume available to non-privileged processes.
766 This is the free space minus the amount of space reserved by the system to prevent critical
767 disk exhaustion errors.
768 Non-privileged programs, like a disk management tool, should use this value to display the
769 space available to the user.
771 .Dv ATTR_VOL_SPACEAVAIL
773 .Dv ATTR_VOL_SPACEFREE
781 .It ATTR_VOL_MINALLOCATION
784 containing the minimum allocation size on the volume in bytes.
785 If you create a file containing one byte, it will consume this much space.
787 .It ATTR_VOL_ALLOCATIONCLUMP
790 containing the allocation clump size on the volume, in bytes.
791 As a file is extended, the file system will attempt to allocate
792 this much space each time in order to reduce fragmentation.
794 .It ATTR_VOL_IOBLOCKSIZE
797 containing the optimal block size when reading or writing data.
802 structure returned by
805 .It ATTR_VOL_OBJCOUNT
808 containing the number of file system objects on the volume.
810 .It ATTR_VOL_FILECOUNT
813 containing the number of files on the volume.
815 .It ATTR_VOL_DIRCOUNT
818 containing the number of directories on the volume.
820 .It ATTR_VOL_MAXOBJCOUNT
823 containing the maximum number of file system objects that can be stored on the volume.
825 .It ATTR_VOL_MOUNTPOINT
828 structure containing the path to the volume's mount point as a
829 UTF-8 encoded, null terminated C string.
830 The attribute data length will not be greater than
836 structure returned by
842 structure containing the name of the volume as a
843 UTF-8 encoded, null terminated C string.
844 The attribute data length will not be greater than
849 This attribute is only read/write if the
850 .Dv VOL_CAP_INT_VOL_RENAME
851 bit is set in the volume capabilities (see below).
854 .It ATTR_VOL_MOUNTFLAGS
857 containing the volume mount flags.
858 This is a copy of the value passed to the
862 when the volume was mounted.
867 structure returned by
870 .It ATTR_VOL_MOUNTEDDEVICE
873 structure that returns the same value as the
877 structure returned by
879 For local volumes this is the path to the device on which the volume is mounted as a
880 UTF-8 encoded, null terminated C string.
881 For network volumes, this is a unique string that identifies the mount.
882 The attribute data length will not be greater than
886 .It ATTR_VOL_ENCODINGSUSED
888 .Vt unsigned long long
889 containing a bitmap of the text encodings used on this volume.
890 For more information about this, see the discussion of
892 in DTS Technote 1150 "HFS Plus Volume Format".
894 .It ATTR_VOL_CAPABILITIES
896 .Vt vol_capabilities_attr_t
897 structure describing the optional features supported by this volume.
898 See below for a discussion of volume capabilities.
903 containing the file system UUID. Typically this will be a
906 .It ATTR_VOL_ATTRIBUTES
908 .Vt vol_attributes_attr_t
909 structure describing the attributes supported by this volume.
910 This structure is discussed below, along with volume capabilities.
914 .Sh DIRECTORY ATTRIBUTES
916 The following directory attributes are defined.
918 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
920 .It ATTR_DIR_LINKCOUNT
923 containing the number of hard links to the directory;
924 this does not include the historical "." and ".." entries.
925 For file systems that do not support hard links to directories,
926 this value will be 1.
928 .It ATTR_DIR_ENTRYCOUNT
931 containing the number of file system objects in the directory, not including
932 any synthetic items. The historical "." and ".." entries are also
933 excluded from this count.
935 .It ATTR_DIR_MOUNTSTATUS
938 containing flags describing what's mounted on the directory.
939 Currently the only flag defined is
940 .Dv DIR_MNTSTATUS_MNTPOINT,
941 which indicates that there is a file system mounted on this directory.
946 Requested directory attributes are not returned for file system objects that
951 The following file attributes are defined.
953 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
955 .It ATTR_FILE_LINKCOUNT
958 containing the number of hard links to this file.
963 structure returned by
966 .It ATTR_FILE_TOTALSIZE
969 containing the total number of bytes in all forks of the file (the logical size).
971 .It ATTR_FILE_ALLOCSIZE
974 containing a count of the bytes on disk used by all of the file's forks (the physical size).
976 .It ATTR_FILE_IOBLOCKSIZE
979 containing the optimal block size when reading or writing this file's data.
981 .It ATTR_FILE_CLUMPSIZE
984 containing the allocation clump size for this file, in bytes.
985 As the file is extended, the file system will attempt to allocate
986 this much space each time in order to reduce fragmentation.
987 This value applies to the data fork.
989 .It ATTR_FILE_DEVTYPE
992 containing the device type for a special device file.
997 structure returned by
1000 .It ATTR_FILE_FILETYPE
1003 that whose value is reserved.
1004 Clients should ignore its value.
1005 New volume format implementations should not support this attribute.
1007 .It ATTR_FILE_FORKCOUNT
1010 containing the number of forks in the file.
1011 No built-in file systems on Mac OS X currently support forks other
1012 than the data and resource fork.
1014 .It ATTR_FILE_FORKLIST
1017 structure containing a list of named forks of the file.
1018 No built-in file systems on Mac OS X currently support forks
1019 other than the data and resource fork.
1020 Because of this, the structure of this attribute's value is not yet defined.
1022 .It ATTR_FILE_DATALENGTH
1025 containing the length of the data fork in bytes (the logical size).
1027 .It ATTR_FILE_DATAALLOCSIZE
1030 containing a count of the bytes on disk used by the data fork (the physical size).
1032 .It ATTR_FILE_DATAEXTENTS
1035 array for the data fork.
1036 The array contains eight
1038 structures which represent the first
1039 eight extents of the fork.
1041 This attributes exists for compatibility reasons.
1042 New clients should not use this attribute.
1043 Rather, they should use the
1049 In current implementations the value may not be entirely accurate for
1050 a variety of reasons.
1052 .It ATTR_FILE_RSRCLENGTH
1055 containing the length of the resource fork in bytes (the logical size).
1057 .It ATTR_FILE_RSRCALLOCSIZE
1060 containing a count of the bytes on disk used by the resource fork (the physical size).
1062 .It ATTR_FILE_RSRCEXTENTS
1065 array for the resource fork.
1066 The array contains eight
1068 structures which represent the first
1069 eight extents of the fork.
1072 .Dv ATTR_FILE_DATAEXTENTS .
1077 File attributes are used for any file system object that is not a directory,
1078 not just ordinary files.
1079 Requested file attributes are not returned for file system objects that
1084 Fork attributes relate to the actual data in the file,
1085 which can be held in multiple named contiguous ranges, or forks.
1086 The following fork attributes are defined.
1088 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
1090 .It ATTR_FORK_TOTALSIZE
1094 containing the length of the fork in bytes (the logical size).
1096 .It ATTR_FORK_ALLOCSIZE
1100 containing a count of the bytes on disk used by the fork (the physical size).
1102 .It ATTR_FORK_RESERVED
1104 You must set this to 0.
1109 Fork attributes are deprecated and all bits are reserved.
1110 They are not properly implemented by any current Mac OS X
1111 volume format implementation.
1112 We strongly recommend that client programs do not request fork attributes.
1113 If you are implementing a volume format, you should not support these attributes.
1115 .Sh VOLUME CAPABILITIES
1117 .\" vol_capabilities_attr_t
1119 Not all volumes support all features.
1121 .Dv ATTR_VOL_CAPABILITIES
1123 .Vt vol_capabilities_attr_t
1124 structure (shown below) that indicates which features are supported by the volume.
1127 typedef u_int32_t vol_capabilities_set_t[4];
1130 #define VOL_CAPABILITIES_FORMAT 0
1131 #define VOL_CAPABILITIES_INTERFACES 1
1132 #define VOL_CAPABILITIES_RESERVED1 2
1133 #define VOL_CAPABILITIES_RESERVED2 3
1136 typedef struct vol_capabilities_attr {
1137 vol_capabilities_set_t capabilities;
1138 vol_capabilities_set_t valid;
1139 } vol_capabilities_attr_t;
1143 The structure contains two fields,
1147 Each consists of an array of four elements.
1148 The arrays are indexed by the following values.
1150 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1152 .It VOL_CAPABILITIES_FORMAT
1153 This element contains information about the volume format.
1155 .Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
1158 .It VOL_CAPABILITIES_INTERFACES
1159 This element contains information about which optional functions are
1160 supported by the volume format implementation.
1162 .Dv VOL_CAP_INT_SEARCHFS
1165 .It VOL_CAPABILITIES_RESERVED1
1167 A file system implementation should set this element to zero.
1168 A client program should ignore this element.
1170 .It VOL_CAPABILITIES_RESERVED2
1172 A file system implementation should set this element to zero.
1173 A client program should ignore this element.
1180 field contains bit sets that indicate which flags are known to the volume format
1182 Each bit indicates whether the contents of the corresponding bit in the
1189 field contains bit sets that indicate whether a particular feature is implemented
1190 by this volume format.
1193 The following bits are defined in the first element (indexed by
1194 .Dv VOL_CAPABILITIES_FORMAT )
1200 .Vt vol_capabilities_attr_t
1203 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1205 .It VOL_CAP_FMT_PERSISTENTOBJECTIDS
1206 If this bit is set the volume format supports persistent object identifiers
1207 and can look up file system objects by their IDs.
1209 .Dv ATTR_CMN_OBJPERMANENTID
1210 for details about how to obtain these identifiers.
1212 .It VOL_CAP_FMT_SYMBOLICLINKS
1213 If this bit is set the volume format supports symbolic links.
1215 .It VOL_CAP_FMT_HARDLINKS
1216 If this bit is set the volume format supports hard links.
1218 .It VOL_CAP_FMT_JOURNAL
1219 If this bit is set the volume format supports a journal used to
1220 speed recovery in case of unplanned restart (such as a power outage
1222 This does not necessarily mean the volume is actively using a journal.
1224 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1226 .It VOL_CAP_FMT_JOURNAL_ACTIVE
1227 If this bit is set the volume is currently using a journal for
1228 speedy recovery after an unplanned restart.
1229 This bit can be set only if
1230 .Dv VOL_CAP_FMT_JOURNAL
1233 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1235 .It VOL_CAP_FMT_NO_ROOT_TIMES
1236 If this bit is set the volume format does not store reliable times for
1237 the root directory, so you should not depend on them to detect changes,
1238 identify volumes across unmount/mount, and so on.
1240 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1242 .It VOL_CAP_FMT_SPARSE_FILES
1243 If this bit is set the volume format supports sparse files,
1244 that is, files which can have 'holes' that have never been written
1245 to, and thus do not consume space on disk.
1246 A sparse file may have an allocated size on disk that is less than its logical length (that is,
1247 .Dv ATTR_FILE_ALLOCSIZE
1249 .Dv ATTR_FILE_TOTALSIZE ).
1252 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1254 .It VOL_CAP_FMT_ZERO_RUNS
1255 For security reasons, parts of a file (runs) that have never been
1256 written to must appear to contain zeroes.
1257 When this bit is set, the volume keeps track of allocated but unwritten
1258 runs of a file so that it can substitute zeroes without actually
1259 writing zeroes to the media.
1260 This provides performance similar to sparse files, but not the space savings.
1262 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1264 .It VOL_CAP_FMT_CASE_SENSITIVE
1265 If this bit is set the volume format treats upper and lower case
1266 characters in file and directory names as different.
1267 Otherwise an upper case character is equivalent to a lower case character,
1268 and you can't have two names that differ solely in the case of
1271 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1273 .It VOL_CAP_FMT_CASE_PRESERVING
1274 If this bit is set the volume format preserves the case of
1275 file and directory names.
1276 Otherwise the volume may change the case of some characters
1277 (typically making them all upper or all lower case).
1279 .Dv VOL_CAP_FMT_CASE_SENSITIVE
1281 .Dv VOL_CAP_FMT_CASE_PRESERVING .
1283 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1285 .It VOL_CAP_FMT_FAST_STATFS
1286 This bit is used as a hint to upper layers to
1289 is fast enough that its results need not be cached by the caller.
1290 A volume format implementation that caches the
1292 information in memory should set this bit.
1293 An implementation that must always read from disk or always perform a network
1294 transaction to satisfy
1296 should not set this bit.
1298 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1300 .It VOL_CAP_FMT_2TB_FILESIZE
1301 If this bit is set the volume format supports file sizes larger
1302 than 4GB, and potentially up to 2TB; it does not indicate
1303 whether the file system supports files larger than that.
1305 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1307 .It VOL_CAP_FMT_OPENDENYMODES
1308 If this bit is set, the volume format supports open deny modes
1309 (e.g., "open for read write, deny write").
1311 .It VOL_CAP_FMT_HIDDEN_FILES
1312 If this bit is set, the volume format supports the
1316 flag is mapped to that volume's native "hidden" or "invisible"
1317 bit (e.g., the invisible bit from the Finder Info extended attribute).
1319 .It VOL_CAP_FMT_PATH_FROM_ID
1320 If this bit is set, the volume format supports the ability to derive a pathname
1321 to the root of the file system given only the ID of an object. This also
1322 implies that object IDs on this file system are persistent and not recycled.
1323 Most file systems will not support this capability.
1325 .It VOL_CAP_FMT_NO_VOLUME_SIZES
1326 If this bit is set the volume format does not support
1327 determining values for total data blocks, available blocks, or free blocks, as in
1336 Historically, those values were set to 0xFFFFFFFF for volumes
1337 that did not support them.
1339 Introduced with Darwin 10.0 (Mac OS X version 10.6).
1341 .It VOL_CAP_FMT_64BIT_OBJECT_IDS
1342 If this bit is set, the volume format uses object IDs that are 64-bit.
1343 This means that ATTR_CMN_FILEID and ATTR_CMN_PARENTID are the primary means of
1344 obtaining object IDs from this volume. The values returned by ATTR_CMN_OBJID,
1345 ATTR_CMN_OBJPERMANENTID, and ATTR_CMN_PAROBJID can be interpreted as 64-bit
1346 object IDs instead of fsobj_id_t.
1351 The following bits are defined in the second element (indexed by
1352 .Dv VOL_CAPABILITIES_INTERFACES )
1358 .Vt vol_capabilities_attr_t
1361 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1363 .It VOL_CAP_INT_SEARCHFS
1364 If this bit is set the volume format implementation supports
1367 .It VOL_CAP_INT_ATTRLIST
1368 If this bit is set the volume format implementation supports
1373 .It VOL_CAP_INT_NFSEXPORT
1374 If this bit is set the volume format implementation allows this volume to be exported via NFS.
1376 .It VOL_CAP_INT_READDIRATTR
1377 If this bit is set the volume format implementation supports
1378 .Xr getdirentriesattr 2 .
1380 .It VOL_CAP_INT_EXCHANGEDATA
1381 If this bit is set the volume format implementation supports
1382 .Xr exchangedata 2 .
1384 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1386 .It VOL_CAP_INT_COPYFILE
1387 If this bit is set the volume format implementation supports the (private and undocumented)
1388 copyfile() function.
1393 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1395 .It VOL_CAP_INT_ALLOCATE
1396 If this bit is set the volume format implementation supports the
1401 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1403 .It VOL_CAP_INT_VOL_RENAME
1404 If this bit is set the volume format implementation allows you to
1405 modify the volume name using
1408 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1410 .It VOL_CAP_INT_ADVLOCK
1411 If this bit is set the volume format implementation supports
1412 advisory locking, that is, the
1420 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1422 .It VOL_CAP_INT_FLOCK
1423 If this bit is set the volume format implementation supports
1434 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1436 .It VOL_CAP_INT_EXTENDED_SECURITY
1437 If this bit is set the volume format implementation supports
1438 extended security controls (ACLs).
1440 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1442 .It VOL_CAP_INT_USERACCESS
1443 If this bit is set the volume format implementation supports the
1444 ATTR_CMN_USERACCESS attribute.
1446 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1448 .It VOL_CAP_INT_MANLOCK
1449 If this bit is set, the volume format implementation supports
1450 AFP-style mandatory byte range locks via
1453 .It VOL_CAP_INT_EXTENDED_ATTR
1454 If this bit is set, the volume format implementation supports
1455 native extended attributes (see
1456 .Xr setxattr 2 Ns ).
1458 .It VOL_CAP_INT_NAMEDSTREAMS
1459 If this bit is set, the volume format implementation supports
1460 native named streams.
1462 .It VOL_CAP_INT_RENAME_SWAP
1463 If this bit is set, the file system supports swapping file system
1468 .It VOL_CAP_INT_RENAME_EXCL
1469 If this bit is set, the file system supports an exclusive rename
1477 .\" vol_attributes_attr_t
1479 A volume can also report which attributes it supports.
1480 This information is returned by the
1481 .Dv ATTR_VOL_ATTRIBUTES
1482 attribute, which returns a
1483 .Vt vol_attributes_attr_t
1484 structure (shown below).
1487 typedef struct attribute_set {
1488 attrgroup_t commonattr; /* common attribute group */
1489 attrgroup_t volattr; /* volume attribute group */
1490 attrgroup_t dirattr; /* directory attribute group */
1491 attrgroup_t fileattr; /* file attribute group */
1492 attrgroup_t forkattr; /* fork attribute group */
1496 typedef struct vol_attributes_attr {
1497 attribute_set_t validattr;
1498 attribute_set_t nativeattr;
1499 } vol_attributes_attr_t;
1505 field consists of a number of bit sets that indicate whether an attribute is
1506 supported by the volume format implementation.
1509 is similar except that the bit sets indicate whether an attribute is supported
1510 natively by the volume format.
1511 An attribute is supported natively if the volume format implementation does not have to do
1512 any complex conversions to access the attribute.
1513 For example, a volume format might support persistent object identifiers, but
1514 doing so requires a complex table lookup that is not part of the core volume
1517 .Dv ATTR_VOL_ATTRIBUTES
1518 attribute would return
1519 .Dv ATTR_CMN_OBJPERMANENTID
1523 .Vt vol_attributes_attr_t ,
1529 Upon successful completion a value of 0 is returned.
1530 Otherwise, a value of -1 is returned and
1532 is set to indicate the error.
1535 Not all volumes support
1537 The best way to test whether a volume supports this function is to
1538 simply call it and check the error result.
1542 if it is not supported on a particular volume.
1547 function has been undocumented for more than two years.
1548 In that time a number of volume format implementations have been created without
1549 a proper specification for the behaviour of this routine.
1550 You may encounter volume format implementations with slightly different
1551 behaviour than what is described here.
1552 Your program is expected to be tolerant of this variant behaviour.
1555 If you're implementing a volume format that supports
1557 you should be careful to support the behaviour specified by this document.
1567 The volume does not support the query.
1570 A component of the path prefix for
1574 .It Bq Er ENAMETOOLONG
1575 A component of a path name for
1579 characters, or an entire path name exceeded
1584 The file system object for
1589 The file descriptor argument for
1591 is not a valid file descriptor.
1594 Search permission is denied for a component of the path prefix for
1598 Too many symbolic links were encountered in translating the pathname
1607 points to an invalid address.
1615 .Dv ATTR_BIT_MAP_COUNT .
1618 You requested an invalid attribute.
1621 You requested an attribute that is not supported for this file system object.
1624 You requested volume attributes and directory or file attributes.
1627 You requested volume attributes but
1629 does not reference the root of the volume.
1632 The volume is read-only but must be modified in order to return this attribute.
1635 An I/O error occurred while reading from or writing to the file system.
1638 In addition to the errors returned by the
1642 function may fail if:
1647 argument does not specify an absolute path and the
1651 nor a valid file descriptor open for searching.
1655 argument is not an absolute path and
1659 nor a file descriptor associated with a directory.
1665 If you request any volume attributes, you must set
1669 field, even though it generates no result in the attribute buffer.
1672 The order that attributes are stored in the attribute buffer almost
1673 invariably matches the order of attribute mask bit values.
1676 (0x00000001) comes before
1678 (0x00000002) because its value is smaller.
1679 When ordering attributes, you should always use the order in which they
1680 are described above.
1685 structure is 64-bits (two 32-bit elements) in 32-bit code, and
1686 128-bits (two 64-bit elements) in 64-bit code; however, it is aligned
1687 on a 4-byte (32-bit) boundary, even in 64-bit code.
1689 If you use a structure
1690 for the attribute data, it must be correctly packed and aligned (see
1694 Inconsistent behavior may be observed when the ATTR_CMN_FULLPATH attribute is requested on
1695 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
1696 natively. Callers should be aware of this when requesting the full path of a hard-linked item, especially
1697 if the full path crosses mount points.
1700 For more caveats, see also the compatibility notes above.
1704 The following code prints the file type and creator of a file,
1705 assuming that the volume supports the required attributes.
1711 #include <sys/attr.h>
1712 #include <sys/errno.h>
1714 #include <sys/vnode.h>
1717 typedef struct attrlist attrlist_t;
1720 struct FInfoAttrBuf {
1722 fsobj_type_t objType;
1723 char finderInfo[32];
1724 } __attribute__((aligned(4), packed));
1725 typedef struct FInfoAttrBuf FInfoAttrBuf;
1728 static int FInfoDemo(const char *path)
1731 attrlist_t attrList;
1732 FInfoAttrBuf attrBuf;
1735 memset(&attrList, 0, sizeof(attrList));
1736 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1737 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1740 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1747 assert(attrBuf.length == sizeof(attrBuf));
1750 printf("Finder information for %s:\en", path);
1751 switch (attrBuf.objType) {
1753 printf("file type = '%.4s'\en", &attrBuf.finderInfo[0]);
1754 printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
1757 printf("directory\en");
1760 printf("other object type, %d\en", attrBuf.objType);
1771 The following code is an alternative implementation that uses nested structures
1772 to group the related attributes.
1779 #include <sys/attr.h>
1780 #include <sys/errno.h>
1782 #include <sys/vnode.h>
1785 typedef struct attrlist attrlist_t;
1788 struct FInfo2CommonAttrBuf {
1789 fsobj_type_t objType;
1790 char finderInfo[32];
1791 } __attribute__((aligned(4), packed));
1792 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
1795 struct FInfo2AttrBuf {
1797 FInfo2CommonAttrBuf common;
1798 } __attribute__((aligned(4), packed));;
1799 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
1802 static int FInfo2Demo(const char *path)
1805 attrlist_t attrList;
1806 FInfo2AttrBuf attrBuf;
1809 memset(&attrList, 0, sizeof(attrList));
1810 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1811 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1814 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1821 assert(attrBuf.length == sizeof(attrBuf));
1824 printf("Finder information for %s:\en", path);
1825 switch (attrBuf.common.objType) {
1828 "file type = '%.4s'\en",
1829 &attrBuf.common.finderInfo[0]
1832 "file creator = '%.4s'\en",
1833 &attrBuf.common.finderInfo[4]
1837 printf("directory\en");
1841 "other object type, %d\en",
1842 attrBuf.common.objType
1854 The following example shows how to deal with variable length attributes.
1855 It assumes that the volume specified by
1857 supports the necessary attributes.
1864 #include <sys/attr.h>
1865 #include <sys/errno.h>
1867 #include <sys/vnode.h>
1870 typedef struct attrlist attrlist_t;
1875 u_int32_t fileCount;
1877 attrreference_t mountPointRef;
1878 attrreference_t volNameRef;
1879 char mountPointSpace[MAXPATHLEN];
1880 char volNameSpace[MAXPATHLEN];
1881 } __attribute__((aligned(4), packed));
1882 typedef struct VolAttrBuf VolAttrBuf;
1885 static int VolDemo(const char *path)
1888 attrlist_t attrList;
1892 memset(&attrList, 0, sizeof(attrList));
1893 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1894 attrList.volattr = ATTR_VOL_INFO
1895 | ATTR_VOL_FILECOUNT
1897 | ATTR_VOL_MOUNTPOINT
1901 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1908 assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace));
1909 assert(attrBuf.length <= sizeof(attrBuf));
1912 printf("Volume information for %s:\en", path);
1913 printf("ATTR_VOL_FILECOUNT: %u\en", attrBuf.fileCount);
1914 printf("ATTR_VOL_DIRCOUNT: %u\en", attrBuf.dirCount);
1916 "ATTR_VOL_MOUNTPOINT: %.*s\en",
1917 (int) attrBuf.mountPointRef.attr_length,
1918 ( ((char *) &attrBuf.mountPointRef)
1919 + attrBuf.mountPointRef.attr_dataoffset )
1922 "ATTR_VOL_NAME: %.*s\en",
1923 (int) attrBuf.volNameRef.attr_length,
1924 ( ((char *) &attrBuf.volNameRef)
1925 + attrBuf.volNameRef.attr_dataoffset )
1934 The following sample demonstrates the need to use packing and alignment
1935 controls; without the attribute, in 64-bit code, the fields of the structure are not
1936 placed at the locations that the kernel expects.
1945 #include <sys/attr.h>
1947 /* The alignment and packing attribute is necessary in 64-bit code */
1948 struct AttrListTimes {
1950 struct timespec st_crtime;
1951 struct timespec st_modtime;
1952 } __attribute__((aligned(4), packed));
1954 main(int argc, char **argv)
1959 for (i = 1; i < argc; i++) {
1960 struct attrlist attrList;
1961 struct AttrListTimes myStat = {0};
1962 char *path = argv[i];
1964 memset(&attrList, 0, sizeof(attrList));
1965 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1966 attrList.commonattr = ATTR_CMN_CRTIME |
1969 rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);
1972 warn("getattrlist(%s)", path);
1975 printf("%s: Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
1986 .Xr exchangedata 2 ,
1988 .Xr getattrlistbulk 2 ,
1998 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
2001 function call appeared in OS X 10.10 .
projects / apple / xnu.git / blob