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.
437 On HFS+ volumes, the ATTR_CMN_OBJID of a file system object is distinct from
438 the ATTR_CMN_OBJID of any hard link to that file system object. Although the
439 ATTR_CMN_OBJID of a file system object may appear similar (in whole
440 or in part) to it's ATTR_CMN_FILEID (see description of ATTR_CMN_FILEID below),
441 \fBno relation between the two attributes should ever be implied.\fP
443 .It ATTR_CMN_OBJPERMANENTID
446 structure that uniquely and persistently identifies the file system object
447 within its volume; persistence implies that this attribute is unaffected by
448 mount/unmount operations on the volume.
450 Some file systems can not return this attribute when the volume is mounted
451 read-only and will fail the request with error
454 (e.g. original HFS modifies on disk structures to generate persistent
455 identifiers, and hence cannot do so if the volume is mounted read only.)
457 .It ATTR_CMN_PAROBJID
460 structure that uniquely identifies the parent directory of the file system
461 object within a mounted volume, for the duration of the volume mount; this
462 identifier is not guaranteed to be persistent for the volume and may change
463 every time the volume is mounted.
466 If a file system object is hard linked from multiple directories, the parent
467 directory returned for this attribute is non deterministic; it can be any one
468 of the parent directories of this object.
470 For some volume formats the computing cost for this attribute is significant;
471 developers are advised to request this attribute sparingly.
476 containing a text encoding hint for
477 the file system object's name.
478 It is included to facilitate the lossless round trip conversion of names between
479 Unicode and traditional Mac OS script encodings.
480 File systems that do not have an appropriate text encoding value should return
481 kTextEncodingMacUnicode.
486 structure containing the time that the file system object
492 structure containing the time that the file system object
498 structure returned by
504 structure containing the time that the file system object's
505 attributes were last modified.
510 structure returned by
516 structure containing the time that the file system object
522 structure returned by
525 .It ATTR_CMN_BKUPTIME
528 structure containing the time that the file system object was
530 This value is for use by backup utilities.
531 The file system stores but does not interpret the value.
533 .It ATTR_CMN_FNDRINFO
534 (read/write) 32 bytes of data for use by the Finder.
535 Equivalent to the concatenation of a
540 (or, for directories, a
543 .Vt ExtendedFolderInfo
546 This attribute is not byte swapped by the file system.
547 The value of multibyte fields on disk is always big endian.
548 When running on a little endian system (such as Darwin on x86),
549 you must byte swap any multibyte fields.
554 containing the owner of the file system object.
559 structure returned by
565 containing the group of the file system object.
570 structure returned by
573 .It ATTR_CMN_ACCESSMASK
576 containing the access permissions of the file system object.
581 structure returned by
583 Only the permission bits of
585 are valid; other bits should be ignored,
586 e.g., by masking with
592 containing file flags.
597 structure returned by
599 For more information about these flags, see
602 .It ATTR_CMN_GEN_COUNT
605 containing a non zero monotonically increasing generation
606 count for this file system object. The generation count tracks
607 the number of times the data in a file system object has been
608 modified. No meaning can be implied from its value. The
609 value of the generation count for a file system object can
610 be compared against a previous value of the same file system
611 object for equality; i.e. an unchanged generation
612 count indicates identical data. Requesting this attribute requires the
613 FSOPT_ATTR_CMN_EXTENDED option flag.
616 A generation count value of 0 is invalid and cannot be used to
617 determine data change.
619 The generation count is invalid while a file is mmap'ed. An invalid
620 generation count value of 0 will be returned for mmap'ed files.
622 .It ATTR_CMN_DOCUMENT_ID
625 containing the document id. The document id is a value assigned
626 by the kernel to a document (which can be a file or directory)
627 and is used to track the data regardless of where it gets moved.
628 The document id survives safe saves; i.e it is sticky to the path it
629 was assigned to. Requesting this attribute requires the
630 FSOPT_ATTR_CMN_EXTENDED option flag.
632 A document id of 0 is invalid.
634 .It ATTR_CMN_USERACCESS
637 containing the effective permissions of the current user
638 (the calling process's effective UID) for this file system object.
639 You can test for read, write, and execute permission using
649 .It ATTR_CMN_EXTENDED_SECURITY
650 A variable-length object (thus an
652 structure) containing a
654 structure, of which only the ACL entry is used.
659 of the owner of the file system object. Analoguous to
660 .Dv ATTR_CMN_OWNERID .
665 of the group to which the file system object belongs.
672 that uniquely identifies the file system object within it's mounted volume.
677 structure returned by
680 .It ATTR_CMN_PARENTID
683 that identifies the parent directory of the file system object.
685 .It ATTR_CMN_FULLPATH
688 structure containing the full path (resolving all symlinks) to
689 the file system object as
690 a UTF-8 encoded, null terminated C string.
691 The attribute data length will not be greater than
693 Inconsistent behavior may be observed when this attribute is requested on
694 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
695 natively. Callers should be aware of this when requesting the full path of a hard-linked item.
697 .It ATTR_CMN_ADDEDTIME
700 that contains the time that the file system object was created or renamed into
701 its containing directory. Note that inconsistent behavior may be observed
702 when this attribute is requested on hard-linked items.
704 .It ATTR_CMN_DATA_PROTECT_FLAGS
707 that contains the file or directory's data protection class.
712 .Sh VOLUME ATTRIBUTES
714 Volume attributes relate to volumes (that is, mounted file systems).
715 The following volume attributes are defined.
717 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
720 For reasons that are not at all obvious, you must set
724 field if you request any other volume attributes.
725 This does not result in any attribute data being added to the attribute buffer.
730 containing the file system type.
735 structure returned by
737 Generally not a useful value.
739 .It ATTR_VOL_SIGNATURE
742 containing the volume signature word.
743 This value is unique within a given file system type and lets you
744 distinguish between different volume formats handled by the same file system.
749 containing the total size of the volume in bytes.
751 .It ATTR_VOL_SPACEFREE
754 containing the free space on the volume in bytes.
756 .It ATTR_VOL_SPACEAVAIL
759 containing the space, in bytes, on the volume available to non-privileged processes.
760 This is the free space minus the amount of space reserved by the system to prevent critical
761 disk exhaustion errors.
762 Non-privileged programs, like a disk management tool, should use this value to display the
763 space available to the user.
765 .Dv ATTR_VOL_SPACEAVAIL
767 .Dv ATTR_VOL_SPACEFREE
775 .It ATTR_VOL_MINALLOCATION
778 containing the minimum allocation size on the volume in bytes.
779 If you create a file containing one byte, it will consume this much space.
781 .It ATTR_VOL_ALLOCATIONCLUMP
784 containing the allocation clump size on the volume, in bytes.
785 As a file is extended, the file system will attempt to allocate
786 this much space each time in order to reduce fragmentation.
788 .It ATTR_VOL_IOBLOCKSIZE
791 containing the optimal block size when reading or writing data.
796 structure returned by
799 .It ATTR_VOL_OBJCOUNT
802 containing the number of file system objects on the volume.
804 .It ATTR_VOL_FILECOUNT
807 containing the number of files on the volume.
809 .It ATTR_VOL_DIRCOUNT
812 containing the number of directories on the volume.
814 .It ATTR_VOL_MAXOBJCOUNT
817 containing the maximum number of file system objects that can be stored on the volume.
819 .It ATTR_VOL_MOUNTPOINT
822 structure containing the path to the volume's mount point as a
823 UTF-8 encoded, null terminated C string.
824 The attribute data length will not be greater than
830 structure returned by
836 structure containing the name of the volume as a
837 UTF-8 encoded, null terminated C string.
838 The attribute data length will not be greater than
843 This attribute is only read/write if the
844 .Dv VOL_CAP_INT_VOL_RENAME
845 bit is set in the volume capabilities (see below).
848 .It ATTR_VOL_MOUNTFLAGS
851 containing the volume mount flags.
852 This is a copy of the value passed to the
856 when the volume was mounted.
861 structure returned by
864 .It ATTR_VOL_MOUNTEDDEVICE
867 structure that returns the same value as the
871 structure returned by
873 For local volumes this is the path to the device on which the volume is mounted as a
874 UTF-8 encoded, null terminated C string.
875 For network volumes, this is a unique string that identifies the mount.
876 The attribute data length will not be greater than
880 .It ATTR_VOL_ENCODINGSUSED
882 .Vt unsigned long long
883 containing a bitmap of the text encodings used on this volume.
884 For more information about this, see the discussion of
886 in DTS Technote 1150 "HFS Plus Volume Format".
888 .It ATTR_VOL_CAPABILITIES
890 .Vt vol_capabilities_attr_t
891 structure describing the optional features supported by this volume.
892 See below for a discussion of volume capabilities.
897 containing the file system UUID. Typically this will be a
900 .It ATTR_VOL_ATTRIBUTES
902 .Vt vol_attributes_attr_t
903 structure describing the attributes supported by this volume.
904 This structure is discussed below, along with volume capabilities.
908 .Sh DIRECTORY ATTRIBUTES
910 The following directory attributes are defined.
912 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
914 .It ATTR_DIR_LINKCOUNT
917 containing the number of hard links to the directory;
918 this does not include the historical "." and ".." entries.
919 For file systems that do not support hard links to directories,
920 this value will be 1.
922 .It ATTR_DIR_ENTRYCOUNT
925 containing the number of file system objects in the directory, not including
926 any synthetic items. The historical "." and ".." entries are also
927 excluded from this count.
929 .It ATTR_DIR_MOUNTSTATUS
932 containing flags describing what's mounted on the directory.
933 Currently the only flag defined is
934 .Dv DIR_MNTSTATUS_MNTPOINT,
935 which indicates that there is a file system mounted on this directory.
940 Requested directory attributes are not returned for file system objects that
945 The following file attributes are defined.
947 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
949 .It ATTR_FILE_LINKCOUNT
952 containing the number of hard links to this file.
957 structure returned by
960 .It ATTR_FILE_TOTALSIZE
963 containing the total number of bytes in all forks of the file (the logical size).
965 .It ATTR_FILE_ALLOCSIZE
968 containing a count of the bytes on disk used by all of the file's forks (the physical size).
970 .It ATTR_FILE_IOBLOCKSIZE
973 containing the optimal block size when reading or writing this file's data.
975 .It ATTR_FILE_CLUMPSIZE
978 containing the allocation clump size for this file, in bytes.
979 As the file is extended, the file system will attempt to allocate
980 this much space each time in order to reduce fragmentation.
981 This value applies to the data fork.
983 .It ATTR_FILE_DEVTYPE
986 containing the device type for a special device file.
991 structure returned by
994 .It ATTR_FILE_FILETYPE
997 that whose value is reserved.
998 Clients should ignore its value.
999 New volume format implementations should not support this attribute.
1001 .It ATTR_FILE_FORKCOUNT
1004 containing the number of forks in the file.
1005 No built-in file systems on Mac OS X currently support forks other
1006 than the data and resource fork.
1008 .It ATTR_FILE_FORKLIST
1011 structure containing a list of named forks of the file.
1012 No built-in file systems on Mac OS X currently support forks
1013 other than the data and resource fork.
1014 Because of this, the structure of this attribute's value is not yet defined.
1016 .It ATTR_FILE_DATALENGTH
1019 containing the length of the data fork in bytes (the logical size).
1021 .It ATTR_FILE_DATAALLOCSIZE
1024 containing a count of the bytes on disk used by the data fork (the physical size).
1026 .It ATTR_FILE_DATAEXTENTS
1029 array for the data fork.
1030 The array contains eight
1032 structures which represent the first
1033 eight extents of the fork.
1035 This attributes exists for compatibility reasons.
1036 New clients should not use this attribute.
1037 Rather, they should use the
1043 In current implementations the value may not be entirely accurate for
1044 a variety of reasons.
1046 .It ATTR_FILE_RSRCLENGTH
1049 containing the length of the resource fork in bytes (the logical size).
1051 .It ATTR_FILE_RSRCALLOCSIZE
1054 containing a count of the bytes on disk used by the resource fork (the physical size).
1056 .It ATTR_FILE_RSRCEXTENTS
1059 array for the resource fork.
1060 The array contains eight
1062 structures which represent the first
1063 eight extents of the fork.
1066 .Dv ATTR_FILE_DATAEXTENTS .
1071 File attributes are used for any file system object that is not a directory,
1072 not just ordinary files.
1073 Requested file attributes are not returned for file system objects that
1078 Fork attributes relate to the actual data in the file,
1079 which can be held in multiple named contiguous ranges, or forks.
1080 The following fork attributes are defined.
1082 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
1084 .It ATTR_FORK_TOTALSIZE
1087 containing the length of the fork in bytes (the logical size).
1089 .It ATTR_FORK_ALLOCSIZE
1092 containing a count of the bytes on disk used by the fork (the physical size).
1097 Fork attributes are not properly implemented by any current Mac OS X
1098 volume format implementation.
1099 We strongly recommend that client programs do not request fork attributes.
1100 If you are implementing a volume format, you should not support these attributes.
1102 .Sh VOLUME CAPABILITIES
1104 .\" vol_capabilities_attr_t
1106 Not all volumes support all features.
1108 .Dv ATTR_VOL_CAPABILITIES
1110 .Vt vol_capabilities_attr_t
1111 structure (shown below) that indicates which features are supported by the volume.
1114 typedef u_int32_t vol_capabilities_set_t[4];
1117 #define VOL_CAPABILITIES_FORMAT 0
1118 #define VOL_CAPABILITIES_INTERFACES 1
1119 #define VOL_CAPABILITIES_RESERVED1 2
1120 #define VOL_CAPABILITIES_RESERVED2 3
1123 typedef struct vol_capabilities_attr {
1124 vol_capabilities_set_t capabilities;
1125 vol_capabilities_set_t valid;
1126 } vol_capabilities_attr_t;
1130 The structure contains two fields,
1134 Each consists of an array of four elements.
1135 The arrays are indexed by the following values.
1137 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1139 .It VOL_CAPABILITIES_FORMAT
1140 This element contains information about the volume format.
1142 .Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
1145 .It VOL_CAPABILITIES_INTERFACES
1146 This element contains information about which optional functions are
1147 supported by the volume format implementation.
1149 .Dv VOL_CAP_INT_SEARCHFS
1152 .It VOL_CAPABILITIES_RESERVED1
1154 A file system implementation should set this element to zero.
1155 A client program should ignore this element.
1157 .It VOL_CAPABILITIES_RESERVED2
1159 A file system implementation should set this element to zero.
1160 A client program should ignore this element.
1167 field contains bit sets that indicate which flags are known to the volume format
1169 Each bit indicates whether the contents of the corresponding bit in the
1176 field contains bit sets that indicate whether a particular feature is implemented
1177 by this volume format.
1180 The following bits are defined in the first element (indexed by
1181 .Dv VOL_CAPABILITIES_FORMAT )
1187 .Vt vol_capabilities_attr_t
1190 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1192 .It VOL_CAP_FMT_PERSISTENTOBJECTIDS
1193 If this bit is set the volume format supports persistent object identifiers
1194 and can look up file system objects by their IDs.
1196 .Dv ATTR_CMN_OBJPERMANENTID
1197 for details about how to obtain these identifiers.
1199 .It VOL_CAP_FMT_SYMBOLICLINKS
1200 If this bit is set the volume format supports symbolic links.
1202 .It VOL_CAP_FMT_HARDLINKS
1203 If this bit is set the volume format supports hard links.
1205 .It VOL_CAP_FMT_JOURNAL
1206 If this bit is set the volume format supports a journal used to
1207 speed recovery in case of unplanned restart (such as a power outage
1209 This does not necessarily mean the volume is actively using a journal.
1211 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1213 .It VOL_CAP_FMT_JOURNAL_ACTIVE
1214 If this bit is set the volume is currently using a journal for
1215 speedy recovery after an unplanned restart.
1216 This bit can be set only if
1217 .Dv VOL_CAP_FMT_JOURNAL
1220 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1222 .It VOL_CAP_FMT_NO_ROOT_TIMES
1223 If this bit is set the volume format does not store reliable times for
1224 the root directory, so you should not depend on them to detect changes,
1225 identify volumes across unmount/mount, and so on.
1227 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1229 .It VOL_CAP_FMT_SPARSE_FILES
1230 If this bit is set the volume format supports sparse files,
1231 that is, files which can have 'holes' that have never been written
1232 to, and thus do not consume space on disk.
1233 A sparse file may have an allocated size on disk that is less than its logical length (that is,
1234 .Dv ATTR_FILE_ALLOCSIZE
1236 .Dv ATTR_FILE_TOTALSIZE ).
1239 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1241 .It VOL_CAP_FMT_ZERO_RUNS
1242 For security reasons, parts of a file (runs) that have never been
1243 written to must appear to contain zeroes.
1244 When this bit is set, the volume keeps track of allocated but unwritten
1245 runs of a file so that it can substitute zeroes without actually
1246 writing zeroes to the media.
1247 This provides performance similar to sparse files, but not the space savings.
1249 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1251 .It VOL_CAP_FMT_CASE_SENSITIVE
1252 If this bit is set the volume format treats upper and lower case
1253 characters in file and directory names as different.
1254 Otherwise an upper case character is equivalent to a lower case character,
1255 and you can't have two names that differ solely in the case of
1258 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1260 .It VOL_CAP_FMT_CASE_PRESERVING
1261 If this bit is set the volume format preserves the case of
1262 file and directory names.
1263 Otherwise the volume may change the case of some characters
1264 (typically making them all upper or all lower case).
1266 .Dv VOL_CAP_FMT_CASE_SENSITIVE
1268 .Dv VOL_CAP_FMT_CASE_PRESERVING .
1270 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1272 .It VOL_CAP_FMT_FAST_STATFS
1273 This bit is used as a hint to upper layers to
1276 is fast enough that its results need not be cached by the caller.
1277 A volume format implementation that caches the
1279 information in memory should set this bit.
1280 An implementation that must always read from disk or always perform a network
1281 transaction to satisfy
1283 should not set this bit.
1285 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1287 .It VOL_CAP_FMT_2TB_FILESIZE
1288 If this bit is set the volume format supports file sizes larger
1289 than 4GB, and potentially up to 2TB; it does not indicate
1290 whether the file system supports files larger than that.
1292 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1294 .It VOL_CAP_FMT_OPENDENYMODES
1295 If this bit is set, the volume format supports open deny modes
1296 (e.g., "open for read write, deny write").
1298 .It VOL_CAP_FMT_HIDDEN_FILES
1299 If this bit is set, the volume format supports the
1303 flag is mapped to that volume's native "hidden" or "invisible"
1304 bit (e.g., the invisible bit from the Finder Info extended attribute).
1306 .It VOL_CAP_FMT_PATH_FROM_ID
1307 If this bit is set, the volume format supports the ability to derive a pathname
1308 to the root of the file system given only the ID of an object. This also
1309 implies that object IDs on this file system are persistent and not recycled.
1310 Most file systems will not support this capability.
1312 .It VOL_CAP_FMT_NO_VOLUME_SIZES
1313 If this bit is set the volume format does not support
1314 determining values for total data blocks, available blocks, or free blocks, as in
1323 Historically, those values were set to 0xFFFFFFFF for volumes
1324 that did not support them.
1326 Introduced with Darwin 10.0 (Mac OS X version 10.6).
1328 .It VOL_CAP_FMT_64BIT_OBJECT_IDS
1329 If this bit is set, the volume format uses object IDs that are 64-bit.
1330 This means that ATTR_CMN_FILEID and ATTR_CMN_PARENTID are the only
1331 legitimate attributes for obtaining object IDs from this volume and the
1332 32-bit fid_objno fields of the fsobj_id_t returned by ATTR_CMN_OBJID,
1333 ATTR_CMN_OBJPERMANENTID, and ATTR_CMN_PAROBJID are undefined.
1338 The following bits are defined in the second element (indexed by
1339 .Dv VOL_CAPABILITIES_INTERFACES )
1345 .Vt vol_capabilities_attr_t
1348 .Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
1350 .It VOL_CAP_INT_SEARCHFS
1351 If this bit is set the volume format implementation supports
1354 .It VOL_CAP_INT_ATTRLIST
1355 If this bit is set the volume format implementation supports
1360 .It VOL_CAP_INT_NFSEXPORT
1361 If this bit is set the volume format implementation allows this volume to be exported via NFS.
1363 .It VOL_CAP_INT_READDIRATTR
1364 If this bit is set the volume format implementation supports
1365 .Xr getdirentriesattr 2 .
1367 .It VOL_CAP_INT_EXCHANGEDATA
1368 If this bit is set the volume format implementation supports
1369 .Xr exchangedata 2 .
1371 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1373 .It VOL_CAP_INT_COPYFILE
1374 If this bit is set the volume format implementation supports the (private and undocumented)
1375 copyfile() function.
1380 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1382 .It VOL_CAP_INT_ALLOCATE
1383 If this bit is set the volume format implementation supports the
1388 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1390 .It VOL_CAP_INT_VOL_RENAME
1391 If this bit is set the volume format implementation allows you to
1392 modify the volume name using
1395 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1397 .It VOL_CAP_INT_ADVLOCK
1398 If this bit is set the volume format implementation supports
1399 advisory locking, that is, the
1407 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1409 .It VOL_CAP_INT_FLOCK
1410 If this bit is set the volume format implementation supports
1421 Introduced with Darwin 7.0 (Mac OS X version 10.3).
1423 .It VOL_CAP_INT_EXTENDED_SECURITY
1424 If this bit is set the volume format implementation supports
1425 extended security controls (ACLs).
1427 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1429 .It VOL_CAP_INT_USERACCESS
1430 If this bit is set the volume format implementation supports the
1431 ATTR_CMN_USERACCESS attribute.
1433 Introduced with Darwin 8.0 (Mac OS X version 10.4).
1435 .It VOL_CAP_INT_MANLOCK
1436 If this bit is set, the volume format implementation supports
1437 AFP-style mandatory byte range locks via
1440 .It VOL_CAP_INT_EXTENDED_ATTR
1441 If this bit is set, the volume format implementation supports
1442 native extended attributes (see
1445 .It VOL_CAP_INT_NAMEDSTREAMS
1446 If this bit is set, the volume format implementation supports
1447 native named streams.
1452 .\" vol_attributes_attr_t
1454 A volume can also report which attributes it supports.
1455 This information is returned by the
1456 .Dv ATTR_VOL_ATTRIBUTES
1457 attribute, which returns a
1458 .Vt vol_attributes_attr_t
1459 structure (shown below).
1462 typedef struct attribute_set {
1463 attrgroup_t commonattr; /* common attribute group */
1464 attrgroup_t volattr; /* volume attribute group */
1465 attrgroup_t dirattr; /* directory attribute group */
1466 attrgroup_t fileattr; /* file attribute group */
1467 attrgroup_t forkattr; /* fork attribute group */
1471 typedef struct vol_attributes_attr {
1472 attribute_set_t validattr;
1473 attribute_set_t nativeattr;
1474 } vol_attributes_attr_t;
1480 field consists of a number of bit sets that indicate whether an attribute is
1481 supported by the volume format implementation.
1484 is similar except that the bit sets indicate whether an attribute is supported
1485 natively by the volume format.
1486 An attribute is supported natively if the volume format implementation does not have to do
1487 any complex conversions to access the attribute.
1488 For example, a volume format might support persistent object identifiers, but
1489 doing so requires a complex table lookup that is not part of the core volume
1492 .Dv ATTR_VOL_ATTRIBUTES
1493 attribute would return
1494 .Dv ATTR_CMN_OBJPERMANENTID
1498 .Vt vol_attributes_attr_t ,
1504 Upon successful completion a value of 0 is returned.
1505 Otherwise, a value of -1 is returned and
1507 is set to indicate the error.
1510 Not all volumes support
1512 The best way to test whether a volume supports this function is to
1513 simply call it and check the error result.
1517 if it is not supported on a particular volume.
1522 function has been undocumented for more than two years.
1523 In that time a number of volume format implementations have been created without
1524 a proper specification for the behaviour of this routine.
1525 You may encounter volume format implementations with slightly different
1526 behaviour than what is described here.
1527 Your program is expected to be tolerant of this variant behaviour.
1530 If you're implementing a volume format that supports
1532 you should be careful to support the behaviour specified by this document.
1542 The volume does not support the query.
1545 A component of the path prefix for
1549 .It Bq Er ENAMETOOLONG
1550 A component of a path name for
1554 characters, or an entire path name exceeded
1559 The file system object for
1564 The file descriptor argument for
1566 is not a valid file descriptor.
1569 Search permission is denied for a component of the path prefix for
1573 Too many symbolic links were encountered in translating the pathname
1582 points to an invalid address.
1590 .Dv ATTR_BIT_MAP_COUNT .
1593 You requested an invalid attribute.
1596 You requested an attribute that is not supported for this file system object.
1599 You requested volume attributes and directory or file attributes.
1602 You requested volume attributes but
1604 does not reference the root of the volume.
1607 The volume is read-only but must be modified in order to return this attribute.
1610 An I/O error occurred while reading from or writing to the file system.
1613 In addition to the errors returned by the
1617 function may fail if:
1622 argument does not specify an absolute path and the
1626 nor a valid file descriptor open for searching.
1630 argument is not an absolute path and
1634 nor a file descriptor associated with a directory.
1640 If you request any volume attributes, you must set
1644 field, even though it generates no result in the attribute buffer.
1647 The order that attributes are stored in the attribute buffer almost
1648 invariably matches the order of attribute mask bit values.
1651 (0x00000001) comes before
1653 (0x00000002) because its value is smaller.
1654 When ordering attributes, you should always use the order in which they
1655 are described above.
1660 structure is 64-bits (two 32-bit elements) in 32-bit code, and
1661 128-bits (two 64-bit elements) in 64-bit code; however, it is aligned
1662 on a 4-byte (32-bit) boundary, even in 64-bit code.
1664 If you use a structure
1665 for the attribute data, it must be correctly packed and aligned (see
1669 Inconsistent behavior may be observed when the ATTR_CMN_FULLPATH attribute is requested on
1670 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
1671 natively. Callers should be aware of this when requesting the full path of a hard-linked item, especially
1672 if the full path crosses mount points.
1675 For more caveats, see also the compatibility notes above.
1679 The following code prints the file type and creator of a file,
1680 assuming that the volume supports the required attributes.
1686 #include <sys/attr.h>
1687 #include <sys/errno.h>
1689 #include <sys/vnode.h>
1692 typedef struct attrlist attrlist_t;
1695 struct FInfoAttrBuf {
1697 fsobj_type_t objType;
1698 char finderInfo[32];
1699 } __attribute__((aligned(4), packed));
1700 typedef struct FInfoAttrBuf FInfoAttrBuf;
1703 static int FInfoDemo(const char *path)
1706 attrlist_t attrList;
1707 FInfoAttrBuf attrBuf;
1710 memset(&attrList, 0, sizeof(attrList));
1711 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1712 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1715 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1722 assert(attrBuf.length == sizeof(attrBuf));
1725 printf("Finder information for %s:\en", path);
1726 switch (attrBuf.objType) {
1728 printf("file type = '%.4s'\en", &attrBuf.finderInfo[0]);
1729 printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
1732 printf("directory\en");
1735 printf("other object type, %d\en", attrBuf.objType);
1746 The following code is an alternative implementation that uses nested structures
1747 to group the related attributes.
1754 #include <sys/attr.h>
1755 #include <sys/errno.h>
1757 #include <sys/vnode.h>
1760 typedef struct attrlist attrlist_t;
1763 struct FInfo2CommonAttrBuf {
1764 fsobj_type_t objType;
1765 char finderInfo[32];
1766 } __attribute__((aligned(4), packed));
1767 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
1770 struct FInfo2AttrBuf {
1772 FInfo2CommonAttrBuf common;
1773 } __attribute__((aligned(4), packed));;
1774 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
1777 static int FInfo2Demo(const char *path)
1780 attrlist_t attrList;
1781 FInfo2AttrBuf attrBuf;
1784 memset(&attrList, 0, sizeof(attrList));
1785 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1786 attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
1789 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1796 assert(attrBuf.length == sizeof(attrBuf));
1799 printf("Finder information for %s:\en", path);
1800 switch (attrBuf.common.objType) {
1803 "file type = '%.4s'\en",
1804 &attrBuf.common.finderInfo[0]
1807 "file creator = '%.4s'\en",
1808 &attrBuf.common.finderInfo[4]
1812 printf("directory\en");
1816 "other object type, %d\en",
1817 attrBuf.common.objType
1829 The following example shows how to deal with variable length attributes.
1830 It assumes that the volume specified by
1832 supports the necessary attributes.
1839 #include <sys/attr.h>
1840 #include <sys/errno.h>
1842 #include <sys/vnode.h>
1845 typedef struct attrlist attrlist_t;
1850 u_int32_t fileCount;
1852 attrreference_t mountPointRef;
1853 attrreference_t volNameRef;
1854 char mountPointSpace[MAXPATHLEN];
1855 char volNameSpace[MAXPATHLEN];
1856 } __attribute__((aligned(4), packed));
1857 typedef struct VolAttrBuf VolAttrBuf;
1860 static int VolDemo(const char *path)
1863 attrlist_t attrList;
1867 memset(&attrList, 0, sizeof(attrList));
1868 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1869 attrList.volattr = ATTR_VOL_INFO
1870 | ATTR_VOL_FILECOUNT
1872 | ATTR_VOL_MOUNTPOINT
1876 err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
1883 assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace));
1884 assert(attrBuf.length <= sizeof(attrBuf));
1887 printf("Volume information for %s:\en", path);
1888 printf("ATTR_VOL_FILECOUNT: %u\en", attrBuf.fileCount);
1889 printf("ATTR_VOL_DIRCOUNT: %u\en", attrBuf.dirCount);
1891 "ATTR_VOL_MOUNTPOINT: %.*s\en",
1892 (int) attrBuf.mountPointRef.attr_length,
1893 ( ((char *) &attrBuf.mountPointRef)
1894 + attrBuf.mountPointRef.attr_dataoffset )
1897 "ATTR_VOL_NAME: %.*s\en",
1898 (int) attrBuf.volNameRef.attr_length,
1899 ( ((char *) &attrBuf.volNameRef)
1900 + attrBuf.volNameRef.attr_dataoffset )
1909 The following sample demonstrates the need to use packing and alignment
1910 controls; without the attribute, in 64-bit code, the fields of the structure are not
1911 placed at the locations that the kernel expects.
1920 #include <sys/attr.h>
1922 /* The alignment and packing attribute is necessary in 64-bit code */
1923 struct AttrListTimes {
1925 struct timespec st_crtime;
1926 struct timespec st_modtime;
1927 } __attribute__((aligned(4), packed));
1929 main(int argc, char **argv)
1934 for (i = 1; i < argc; i++) {
1935 struct attrlist attrList;
1936 struct AttrListTimes myStat = {0};
1937 char *path = argv[i];
1939 memset(&attrList, 0, sizeof(attrList));
1940 attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
1941 attrList.commonattr = ATTR_CMN_CRTIME |
1944 rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);
1947 warn("getattrlist(%s)", path);
1950 printf("%s: Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
1961 .Xr exchangedata 2 ,
1963 .Xr getattrlistbulk 2 ,
1973 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
1976 function call appeared in OS X 10.10 .
projects / apple / xnu.git / blob