.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
-.\"
+.\"
.\" The contents of this file constitute Original Code as defined in and
.\" are subject to the Apple Public Source License Version 1.1 (the
.\" "License"). You may not use this file except in compliance with the
.\" License. Please obtain a copy of the License at
.\" http://www.apple.com/publicsource and read it before using this file.
-.\"
+.\"
.\" This Original Code and all software distributed under the License are
.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
.\" License for the specific language governing rights and limitations
.\" under the License.
-.\"
+.\"
.\" @(#)getattrlist.2
.
-.Dd October 14, 2004
+.Dd February 25, 2014
.Dt GETATTRLIST 2
.Os Darwin
.Sh NAME
-.Nm getattrlist
+.Nm getattrlist ,
+.Nm fgetattrlist ,
+.Nm getattrlistat
.Nd get file system attributes
.Sh SYNOPSIS
.Fd #include <sys/attr.h>
.Ft int
.Fn getattrlist "const char* path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
.
+.Ft int
+.Fn fgetattrlist "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
+.Ft int
+.Fo getattrlistat
+.Fa "int fd" "const char *path" "struct attrlist * attrList" "void * attrBuf"
+.Fa "size_t attrBufSize" "unsigned long options"
+.Fc
.Sh DESCRIPTION
The
.Fn getattrlist
function returns attributes (that is, metadata) of file system objects.
-You can think of
+.Fn getattrlist
+works on the file system object named by
+.Fa path ,
+while
+.Fn fgetattrlist
+works on the provided file descriptor
+.Fa fd .
+.Pp
+The
+.Fn getattrlistat
+system call is equivalent to
+.Fn getattrlist
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the attributes are returned for the file system object named by
+path relative to the directory associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+If
+.Fn getattrlistat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is
+identical to a call to
+.Fn getattrlist .
+.Pp
+You can think of
.Fn getattrlist
as a seriously enhanced version of
.Xr stat 2 .
-The function returns attributes about the file system object specified by
-.Fa path
-in the buffer specified by
+The functions return attributes about the specified file system object
+into the buffer specified by
.Fa attrBuf
and
.Fa attrBufSize .
-The
-.Fa attrList
-parameter determines what attributes are returned.
-The
-.Fa options
-parameter lets you control specific aspects of the function's behaviour.
-.Pp
-.
-The
-.Fn getattrlist
-function is only supported by certain volume format implementations.
-For maximum compatibility, client programs should use high-level APIs
-(such as the Carbon File Manager) to access file system attributes.
-These high-level APIs include logic to emulate file system attributes
-on volumes that don't support
-.Fn getattrlist .
+The
+.Fa attrList
+parameter determines what attributes are returned.
+The
+.Fa options
+parameter lets you control specific aspects of the function's behavior.
.Pp
.
Not all volumes support all attributes.
-See the discussion of
-.Dv ATTR_VOL_ATTRIBUTES
-for a discussion of how to determine whether a particular volume supports a
+See the discussion of
+.Dv ATTR_VOL_ATTRIBUTES
+for a discussion of how to determine whether a particular volume supports a
particular attribute.
.Pp
-Furthermore, you should only request the attributes that you need.
-Some attributes are expensive to calculate on some volume formats.
-For example,
-.Dv ATTR_DIR_ENTRYCOUNT
+Furthermore, you should only request the attributes that you need.
+Some attributes are expensive to calculate on some volume formats.
+For example,
+.Dv ATTR_DIR_ENTRYCOUNT
is usually expensive to calculate on non-HFS [Plus] volumes.
If you don't need a particular attribute, you should not ask for it.
.Pp
The
.Fa path
parameter must reference a valid file system object.
-Read, write or execute permission of the object itself is not required, but
-all directories listed in the path name leading to the object must be
+Read, write or execute permission of the object itself is not required, but
+all directories listed in the path name leading to the object must be
searchable.
.Pp
.
.
The
.Fa attrList
-parameter is a pointer to an
-.Vt attrlist
+parameter is a pointer to an
+.Vt attrlist
structure, as defined by
.Aq Pa sys/attr.h
(shown below).
It determines what attributes are returned by the function.
-You are responsible for filling out all fields of this structure before calling the function.
+You are responsible for filling out all fields of this structure before calling the function.
.Bd -literal
typedef u_int32_t attrgroup_t;
.Pp
.
.\" attrlist elements
.
-The fields of the
+The fields of the
.Vt attrlist
structure are defined as follows.
.Bl -tag -width XXXbitmapcount
.
.It bitmapcount
Number of attribute bit sets in the structure.
-In current systems you must set this to
+In current systems you must set this to
.Dv ATTR_BIT_MAP_COUNT .
.
.It reserved
.
.It commonattr
A bit set that specifies the common attributes that you require.
-Common attributes relate to all types of file system objects.
+Common attributes relate to all types of file system objects.
See below for a description of these attributes.
.
.It volattr
A bit set that specifies the volume attributes that you require.
Volume attributes relate to volumes (that is, mounted file systems).
See below for a description of these attributes.
-If you request volume attributes,
+If you request volume attributes,
.Fa path
must reference the root of a volume.
-In addition, you can't request volume attributes if you also request
+In addition, you can't request volume attributes if you also request
file or directory attributes.
.
.It dirattr
.
.It forkattr
A bit set that specifies the fork attributes that you require.
-Fork attributes relate to the actual data in the file,
+Fork attributes relate to the actual data in the file,
which can be held in multiple named contiguous ranges, or forks.
See below for a description of these attributes.
+If the FSOPT_ATTR_CMN_EXTENDED option is given, this bit set is reinterpreted
+as extended common attributes attributes, also described below.
.
.El
.Pp
.
-Unless otherwise noted in the lists below, attributes are read-only.
-Attributes labelled as read/write can be set using
+Unless otherwise noted in the lists below, attributes are read-only.
+Attributes labelled as read/write can be set using
.Xr setattrlist 2 .
.Pp
.
.
The
.Fa attrBuf
-and
+and
.Fa attrBufSize
-parameters specify a buffer into which the function places attribute values.
-The format of this buffer is sufficiently complex that its description
+parameters specify a buffer into which the function places attribute values.
+The format of this buffer is sufficiently complex that its description
requires a separate section (see below).
The initial contents of this buffer are ignored.
.Pp
The
.Fa options
parameter is a bit set that controls the behaviour of
-.Fn getattrlist .
+the functions.
The following option bits are defined.
.
-.Bl -tag -width XXXbitmapcount
+.Bl -tag -width FSOPT_PACK_INVAL_ATTRS
.
.It FSOPT_NOFOLLOW
-If this bit is set,
-.Fn getattrlist
-will not follow a symlink if it occurs as
+If this bit is set,
+.Fn getattrlist
+will not follow a symlink if it occurs as
the last component of
.Fa path .
.
+.It FSOPT_REPORT_FULLSIZE
+The size of the attributes reported (in the first
+.Vt u_int32_t
+field in the attribute buffer) will be the size needed to hold all the
+requested attributes; if not set, only the attributes actually returned
+will be reported. This allows the caller to determine if any truncation
+occurred.
+.
+.It FSOPT_PACK_INVAL_ATTRS
+If this is bit is set, then all requested attributes, even ones that are
+not supported by the object or file system, will be returned. Default values
+will be used for the invalid ones. Requires that
+.Dv ATTR_CMN_RETURNED_ATTRS
+be requested.
+.
+.It FSOPT_ATTR_CMN_EXTENDED
+If this is bit is set, then
+.Dv ATTR_CMN_GEN_COUNT
+and
+.Dv ATTR_CMN_DOCUMENT_ID
+can be requested. When this option is used, forkattrs are reinterpreted as a
+set of extended common attributes.
+.
.El
.
.Sh ATTRIBUTE BUFFER
.
-The data returned in the buffer described by
-.Fa attrBuf
-and
-.Fa attrBufSize
+The data returned in the buffer described by
+.Fa attrBuf
+and
+.Fa attrBufSize
is formatted as follows.
.Pp
.
.Bl -enum
.
.It
-The first element of the buffer is a
-.Vt unsigned long
-that contains the overall length, in bytes, of the attributes returned.
-This size includes the length field itself.
+The first element of the buffer is a
+.Vt u_int32_t
+that contains the overall length, in bytes, of the attributes returned.
+This size includes the length field itself.
.
.It
-Following the length field is a list of attributes.
-Each attribute is represented by a field of its type,
-where the type is given as part of the attribute description (below).
+Following the length field is a list of attributes.
+Each attribute is represented by a field of its type,
+where the type is given as part of the attribute description (below).
.
.It
-The attributes are placed into the attribute buffer in the order
+The attributes are placed into the attribute buffer in the order
that they are described below.
.
+.It
+Each attribute is aligned to a 4-byte boundary (including 64-bit data types).
.El
.Pp
.
-If the attribute is of variable length, it is represented
-in the list by an
-.Vt attrreference
-structure, as defined by
+If the attribute is of variable length, it is represented
+in the list by an
+.Vt attrreference
+structure, as defined by
.Aq Pa sys/attr.h
(shown below).
.
.Bd -literal
typedef struct attrreference {
- long attr_dataoffset;
- size_t attr_length;
+ int32_t attr_dataoffset;
+ u_int32_t attr_length;
} attrreference_t;
.Ed
.Pp
.
This structure contains a 'pointer' to the variable length attribute data.
-The
-.Fa attr_length
-field is the length of the attribute data (in bytes).
-The
-.Fa attr_dataoffset
-field is the offset in bytes from the
-.Vt attrreference
-structure
-to the attribute data.
-This offset will always be a multiple of sizeof(unsigned long) bytes,
-so you can safely access common data types without fear of alignment
+The
+.Fa attr_length
+field is the length of the attribute data (in bytes).
+The
+.Fa attr_dataoffset
+field is the offset in bytes from the
+.Vt attrreference
+structure
+to the attribute data.
+This offset will always be a multiple of sizeof(u_int32_t) bytes,
+so you can safely access common data types without fear of alignment
exceptions.
.Pp
.
-The
-.Fn getattrlist
-function will silently truncate attribute data if
-.Fa attrBufSize
-is too small.
-The length field at the front of the attribute list always represents
-the length of the data actually copied into the attribute buffer.
-If the data is truncated, there is no easy way to determine the
-buffer size that's required to get all of the requested attributes.
-You should always pass an
-.Fa attrBufSize
-that is large enough to accommodate the known size of the attributes
+The
+.Fn getattrlist
+function will silently truncate attribute data if
+.Fa attrBufSize
+is too small.
+The length field at the front of the attribute list always represents
+the length of the data actually copied into the attribute buffer.
+If the data is truncated, there is no easy way to determine the
+buffer size that's required to get all of the requested attributes.
+You should always pass an
+.Fa attrBufSize
+that is large enough to accommodate the known size of the attributes
in the attribute list (including the leading length field).
.Pp
.
-Because the returned attributes are simply truncated if the buffer is
-too small, it's possible for a variable length attribute to reference
-data beyond the end of the attribute buffer. That is, it's possible
-for the attribute data to start beyond the end of the attribute buffer
-(that is, if
-.Fa attrRef
-is a pointer to the
+Because the returned attributes are simply truncated if the buffer is
+too small, it's possible for a variable length attribute to reference
+data beyond the end of the attribute buffer. That is, it's possible
+for the attribute data to start beyond the end of the attribute buffer
+(that is, if
+.Fa attrRef
+is a pointer to the
.Vt attrreference_t ,
-( ( (char *)
-.Fa attrRef
-) +
-.Fa attr_dataoffset
-) > ( ( (char *)
-.Fa attrBuf
-) +
-.Fa attrSize
-) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is,
-( ( (char *)
-.Fa attrRef
-) +
-.Fa attr_dataoffset
-+
-.Fa attr_datalength
-) > ( ( (char *)
-.Fa attrBuf
-) +
-.Fa attrSize
+( ( (char *)
+.Fa attrRef
+) +
+.Fa attr_dataoffset
+) > ( ( (char *)
+.Fa attrBuf
+) +
+.Fa attrSize
+) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is,
+( ( (char *)
+.Fa attrRef
+) +
+.Fa attr_dataoffset
++
+.Fa attr_datalength
+) > ( ( (char *)
+.Fa attrBuf
+) +
+.Fa attrSize
) ).
-If this happens you must increase the size of the buffer and call
-.Fn getattrlist
+If this happens you must increase the size of the buffer and call
+.Fn getattrlist
to get an accurate copy of the attribute.
.
.Sh COMMON ATTRIBUTES
.
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
+.It ATTR_CMN_RETURNED_ATTRS
+An
+.Vt attribute_set_t
+structure which is used to report which of the requested attributes
+were actually returned. This attribute, when requested, will always
+be the first attribute returned. By default, unsupported attributes
+will be skipped (i.e. not packed into the output buffer). This behavior
+can be over-ridden using the FSOPT_PACK_INVAL_ATTRS option flag. Both
+.Xr getattrlist 2 and
+.Xr getatttrlistbulk 2 support this attribute while
+.Xr searchfs 2 does not.
+.
.It ATTR_CMN_NAME
-An
-.Vt attrreference
-structure containing the name of the file system object as
+An
+.Vt attrreference
+structure containing the name of the file system object as
UTF-8 encoded, null terminated C string.
-The attribute data length will not be greater than
-.Dv NAME_MAX +
-1.
+The attribute data length will not be greater than
+.Dv NAME_MAX
++ 1 characters, which is
+.Dv NAME_MAX
+* 3 + 1 bytes (as one UTF-8-encoded character may
+take up to three bytes).
.Pp
.
.It ATTR_CMN_DEVID
-A
-.Vt dev_t
-containing the device number of the device on which this
+A
+.Vt dev_t
+containing the device number of the device on which this
file system object's volume is mounted.
-Equivalent to the
-.Fa st_dev
-field of the
-.Vt stat
-structure returned by
+Equivalent to the
+.Fa st_dev
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_CMN_FSID
-An
-.Vt fsid_t
-structure containing the file system identifier for the volume on which
+An
+.Vt fsid_t
+structure containing the file system identifier for the volume on which
the file system object resides.
-Equivalent to the
-.Fa f_fsid
-field of the
-.Vt statfs
-structure returned by
+Equivalent to the
+.Fa f_fsid
+field of the
+.Vt statfs
+structure returned by
.Xr statfs 2 .
.
-.Pp
-This value is not related to the file system ID from traditional Mac OS (for example,
-the
-.Fa filesystemID
-field of the
-.Vt FSVolumeInfo
-structure returned by Carbon's FSGetVolumeInfo() function).
-On current versions of Mac OS X that value is synthesised by the Carbon File Manager.
-.
.It ATTR_CMN_OBJTYPE
-An
-.Vt fsobj_type_t
-that identifies the type of file system object.
-The values are taken from
-.Vt enum vtype
-in
+An
+.Vt fsobj_type_t
+that identifies the type of file system object.
+The values are taken from
+.Vt enum vtype
+in
.Aq Pa sys/vnode.h .
.
.It ATTR_CMN_OBJTAG
-An
-.Vt fsobj_tag_t
+An
+.Vt fsobj_tag_t
that identifies the type of file system containing the object.
-The values are taken from
-.Vt enum vtagtype
+The values are taken from
+.Vt enum vtagtype
in
.Aq Pa sys/vnode.h .
.
.It ATTR_CMN_OBJID
-An
-.Vt fsobj_id_t
-structure that uniquely identifies the file system object
-within its volume.
-The fid_generation field of this structure will be zero for all non-root callers
-(effective UID not 0).
-This identifier need not be persistent across an unmount/mount sequence.
-.Pp
-.
-Some volume formats use well known values for the
-.Fa fid_objno
-field for the root directory (2) and the parent of root directory (1).
-This is not a required behaviour of this attribute.
+An
+.Vt fsobj_id_t
+structure that uniquely identifies the file system object within a mounted
+volume for the duration of it's mount; this identifier is not guaranteed to be
+persistent for the volume and may change every time the volume is mounted.
+.Pp
+On HFS+ volumes, the ATTR_CMN_OBJID of a file system object is distinct from
+the ATTR_CMN_OBJID of any hard link to that file system object. Although the
+ATTR_CMN_OBJID of a file system object may appear similar (in whole
+or in part) to it's ATTR_CMN_FILEID (see description of ATTR_CMN_FILEID below),
+\fBno relation between the two attributes should ever be implied.\fP
+.Pp
+ATTR_CMN_OBJID is deprecated sarting with macOS 10.13, iOS 11.0, watchOS 4.0 and
+tvOS 11.0 and ATTR_CMNEXT_LINKID should be used in its place.
+ATTR_CMN_OBJID can only be used on older operating systems only if the file
+system doesn't 64 bit IDs. See the
+.Fn getLinkIDInfo
+function in the EXAMPLES section.
.
.It ATTR_CMN_OBJPERMANENTID
-An
-.Vt fsobj_id_t
-structure that uniquely identifies the file system object
-within its volume.
-The fid_generation field of this structure will be zero for all non-root callers
-(effective UID not 0).
-This identifier should be persistent across an unmount/mount sequence.
-.Pp
-Some file systems (for example, original HFS) may need to modify the on-disk
-structure to return a persistent identifier.
-If such a file system is mounted read-only, an attempt to get this attribute
-will fail with the error
-.Dv EROFS .
+An
+.Vt fsobj_id_t
+structure that uniquely and persistently identifies the file system object
+within its volume; persistence implies that this attribute is unaffected by
+mount/unmount operations on the volume.
+.Pp
+Some file systems can not return this attribute when the volume is mounted
+read-only and will fail the request with error
+.Dv EROFS.
+.br
+(e.g. original HFS modifies on disk structures to generate persistent
+identifiers, and hence cannot do so if the volume is mounted read only.)
.
.It ATTR_CMN_PAROBJID
-An
-.Vt fsobj_id_t
-structure that identifies the parent directory of the file system object.
-The fid_generation field of this structure will be zero for all non-root callers
-(effective UID not 0).
-Equivalent to the ATTR_CMN_OBJID attribute of the parent directory.
-This identifier need not be persistent across an unmount/mount sequence.
+An
+.Vt fsobj_id_t
+structure that uniquely identifies the parent directory of the file system
+object within a mounted volume, for the duration of the volume mount; this
+identifier is not guaranteed to be persistent for the volume and may change
+every time the volume is mounted.
.Pp
.
-On a volume that supports hard links, a multiply linked file has no unique parent.
-This attribute will return an unspecified parent.
-.Pp
+If a file system object is hard linked from multiple directories, the parent
+directory returned for this attribute is non deterministic; it can be any one
+of the parent directories of this object.
.
-For some volume formats this attribute is very expensive to calculate.
+For some volume formats the computing cost for this attribute is significant;
+developers are advised to request this attribute sparingly.
.
.It ATTR_CMN_SCRIPT
-(read/write) A
-.Vt text_encoding_t
-containing a text encoding hint for
-the file system object's name.
-It is included to facilitate the lossless round trip conversion of names between
+(read/write) A
+.Vt text_encoding_t
+containing a text encoding hint for
+the file system object's name.
+It is included to facilitate the lossless round trip conversion of names between
Unicode and traditional Mac OS script encodings.
-The values are defined in
-.Aq Pa CarbonCore/TextCommon.h .
-File systems that do not have an appropriate text encoding value should return
-kTextEncodingMacUnicode.
-See DTS Q&A 1173 "File Manager Text Encoding Hints".
+File systems that do not have an appropriate text encoding value should return
+kTextEncodingMacUnicode.
.
.It ATTR_CMN_CRTIME
-(read/write) A
-.Vt timespec
-structure containing the time that the file system object
-was created.
+(read/write) A
+.Vt timespec
+structure containing the time that the file system object
+was created.
.
.It ATTR_CMN_MODTIME
-(read/write) A
-.Vt timespec
-structure containing the time that the file system object
-was last modified.
-Equivalent to the
-.Fa st_mtimespec
-field of the
-.Vt stat
-structure returned by
+(read/write) A
+.Vt timespec
+structure containing the time that the file system object
+was last modified.
+Equivalent to the
+.Fa st_mtimespec
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_CMN_CHGTIME
-(read/write) A
-.Vt timespec
-structure containing the time that the file system object's
-attributes were last modified.
-Equivalent to the
-.Fa st_ctimespec
-field of the
-.Vt stat
-structure returned by
+A
+.Vt timespec
+structure containing the time that the file system object's
+attributes were last modified.
+Equivalent to the
+.Fa st_ctimespec
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_CMN_ACCTIME
-(read/write) A
-.Vt timespec
-structure containing the time that the file system object
-was last accessed.
-Equivalent to the
-.Fa st_atimespec
-field of the
-.Vt stat
-structure returned by
+(read/write) A
+.Vt timespec
+structure containing the time that the file system object
+was last accessed.
+Equivalent to the
+.Fa st_atimespec
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_CMN_BKUPTIME
-(read/write) A
-.Vt timespec
-structure containing the time that the file system object was
-last backed up.
-This value is for use by backup utilities.
+(read/write) A
+.Vt timespec
+structure containing the time that the file system object was
+last backed up.
+This value is for use by backup utilities.
The file system stores but does not interpret the value.
.
.It ATTR_CMN_FNDRINFO
(read/write) 32 bytes of data for use by the Finder.
-Equivalent to the concatenation of a
-.Vt FileInfo
-structure and an
-.Vt ExtendedFileInfo
-structure
-(or, for directories, a
-.Vt FolderInfo
-structure and an
-.Vt ExtendedFolderInfo
+Equivalent to the concatenation of a
+.Vt FileInfo
+structure and an
+.Vt ExtendedFileInfo
+structure
+(or, for directories, a
+.Vt FolderInfo
+structure and an
+.Vt ExtendedFolderInfo
structure).
-These structures are defined in
-.Aq Pa CarbonCore/Finder.h .
.Pp
This attribute is not byte swapped by the file system.
-The value of multibyte fields on disk is always big endian.
-When running on a little endian system (such as Darwin on x86),
+The value of multibyte fields on disk is always big endian.
+When running on a little endian system (such as Darwin on x86),
you must byte swap any multibyte fields.
.
.It ATTR_CMN_OWNERID
-(read/write) A
-.Vt uid_t
-containing the owner of the file system object.
-Equivalent to the
-.Fa st_uid
-field of the
-.Vt stat
-structure returned by
+(read/write) A
+.Vt uid_t
+containing the owner of the file system object.
+Equivalent to the
+.Fa st_uid
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_CMN_GRPID
-(read/write) A
-.Vt gid_t
-containing the group of the file system object.
-Equivalent to the
-.Fa st_gid
-field of the
-.Vt stat
-structure returned by
+(read/write) A
+.Vt gid_t
+containing the group of the file system object.
+Equivalent to the
+.Fa st_gid
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_CMN_ACCESSMASK
-(read/write) A
-.Vt mode_t
-containing the access permissions of the file system object.
-Equivalent to the
-.Fa st_mode
-field of the
-.Vt stat
-structure returned by
+(read/write) A
+.Vt u_int32_t
+containing the access permissions of the file system object.
+Equivalent to the
+.Fa st_mode
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
-.
-.It ATTR_CMN_NAMEDATTRCOUNT
-A
-.Vt unsigned long
-containing the number of named attributes of the file system object.
-No built-in file systems on Mac OS X currently support named attributes.
-.
-.It ATTR_CMN_NAMEDATTRLIST
-An
-.Vt attrreference
-structure containing a list of named attributes of the file system object.
-No built-in file systems on Mac OS X currently support named attributes.
-Because of this, the structure of this attribute's value is not yet defined.
+Only the permission bits of
+.Fa st_mode
+are valid; other bits should be ignored,
+e.g., by masking with
+.Dv ~S_IFMT .
.
.It ATTR_CMN_FLAGS
-(read/write) A
-.Vt unsigned long
+(read/write) A
+.Vt u_int32_t
containing file flags.
-Equivalent to the
-.Fa st_flags
-field of the
-.Vt stat
-structure returned by
+Equivalent to the
+.Fa st_flags
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
-For more information about these flags, see
+For more information about these flags, see
.Xr chflags 2 .
+.
+.It ATTR_CMN_GEN_COUNT
+A
+.Vt u_int32_t
+containing a non zero monotonically increasing generation
+count for this file system object. The generation count tracks
+the number of times the data in a file system object has been
+modified. No meaning can be implied from its value. The
+value of the generation count for a file system object can
+be compared against a previous value of the same file system
+object for equality; i.e. an unchanged generation
+count indicates identical data. Requesting this attribute requires the
+FSOPT_ATTR_CMN_EXTENDED option flag.
.Pp
.
-The order that attributes are placed into the attribute buffer
-almost invariably matches the order of the attribute mask bit values.
-The exception is
-.Dv ATTR_CMN_FLAGS .
-If its order was based on its bit position, it would be before
-the
-.Dv ATTR_CMN_NAMEDATTRCOUNT
-/
-.Dv ATTR_CMN_NAMEDATTRLIST
-pair, however,
-it is placed in the buffer after them.
+A generation count value of 0 is invalid and cannot be used to
+determine data change.
+.Pp
+The generation count is invalid while a file is mmap'ed. An invalid
+generation count value of 0 will be returned for mmap'ed files.
+.
+.It ATTR_CMN_DOCUMENT_ID
+A
+.Vt u_int32_t
+containing the document id. The document id is a value assigned
+by the kernel to a document (which can be a file or directory)
+and is used to track the data regardless of where it gets moved.
+The document id survives safe saves; i.e it is sticky to the path it
+was assigned to. Requesting this attribute requires the
+FSOPT_ATTR_CMN_EXTENDED option flag.
+.Pp
+A document id of 0 is invalid.
.
.It ATTR_CMN_USERACCESS
-A
-.Vt unsigned long
-containing the effective permissions of the current user
-(the calling process's effective UID) for this file system object.
-You can test for read, write, and execute permission using
+A
+.Vt u_int32_t
+containing the effective permissions of the current user
+(the calling process's effective UID) for this file system object.
+You can test for read, write, and execute permission using
.Dv R_OK ,
.Dv W_OK ,
and
-.Dv X_OK ,
-respectively. See
-.Xr access 2
+.Dv X_OK ,
+respectively.
+See
+.Xr access 2
for more details.
.
+.It ATTR_CMN_EXTENDED_SECURITY
+A variable-length object (thus an
+.Vt attrreference
+structure) containing a
+.Vt kauth_filesec
+structure, of which only the ACL entry is used.
+.
+.It ATTR_CMN_UUID
+A
+.Vt guid_t
+of the owner of the file system object. Analoguous to
+.Dv ATTR_CMN_OWNERID .
+.
+.It ATTR_CMN_GRPUUID
+A
+.Vt guid_t
+of the group to which the file system object belongs.
+Analoguous to
+.Dv ATTR_CMN_GRPID .
+.
+.It ATTR_CMN_FILEID
+A
+.Vt u_int64_t
+that uniquely identifies the file system object within its mounted volume.
+Equivalent to
+.Fa st_ino
+field of the
+.Vt stat
+structure returned by
+.Xr stat 2 .
+.
+.It ATTR_CMN_PARENTID
+A
+.Vt u_int64_t
+that identifies the parent directory of the file system object.
+.
+.It ATTR_CMN_FULLPATH
+An
+.Vt attrreference
+structure containing the full path (resolving all symlinks) to
+the file system object as
+a UTF-8 encoded, null terminated C string.
+The attribute data length will not be greater than
+.Dv PATH_MAX.
+Inconsistent behavior may be observed when this attribute is requested on
+hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
+natively. Callers should be aware of this when requesting the full path of a hard-linked item.
+.
+.It ATTR_CMN_ADDEDTIME
+A
+.Vt timespec
+that contains the time that the file system object was created or renamed into
+its containing directory. Note that inconsistent behavior may be observed
+when this attribute is requested on hard-linked items.
+.
+.It ATTR_CMN_DATA_PROTECT_FLAGS
+A
+.Vt u_int32_t
+that contains the file or directory's data protection class.
+.Pp
+.
.El
.
.Sh VOLUME ATTRIBUTES
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
.It ATTR_VOL_INFO
-For reasons that are not at all obvious, you must set
-.Dv ATTR_VOL_INFO
-in the
+For reasons that are not at all obvious, you must set
+.Dv ATTR_VOL_INFO
+in the
.Fa volattr
field if you request any other volume attributes.
This does not result in any attribute data being added to the attribute buffer.
.
.It ATTR_VOL_FSTYPE
-A
-.Vt unsigned long
+A
+.Vt u_int32_t
containing the file system type.
-Equivalent to the
-.Fa f_type
-field of the
-.Vt statfs
-structure returned by
+Equivalent to the
+.Fa f_type
+field of the
+.Vt statfs
+structure returned by
.Xr statfs 2 .
Generally not a useful value.
.
.It ATTR_VOL_SIGNATURE
-A
-.Vt unsigned long
-containing the volume signature word.
-This value is unique within a given file system type and lets you
+A
+.Vt u_int32_t
+containing the volume signature word.
+This value is unique within a given file system type and lets you
distinguish between different volume formats handled by the same file system.
-See
-.Aq Pa CarbonCore/Files.h
-for more details.
.
.It ATTR_VOL_SIZE
-An
+An
.Vt off_t
containing the total size of the volume in bytes.
.
.It ATTR_VOL_SPACEFREE
-An
+An
.Vt off_t
containing the free space on the volume in bytes.
.
.It ATTR_VOL_SPACEAVAIL
-An
+An
.Vt off_t
-containing the space, in bytes, on the volume available to non-privileged processes.
-This is the free space minus the amount of space reserved by the system to prevent critical
-disk exhaustion errors.
-Non-privileged programs, like a disk management tool, should use this value to display the
+containing the space, in bytes, on the volume available to non-privileged processes.
+This is the free space minus the amount of space reserved by the system to prevent critical
+disk exhaustion errors.
+Non-privileged programs, like a disk management tool, should use this value to display the
space available to the user.
.Pp
-.Dv ATTR_VOL_SPACEAVAIL
-is to
-.Dv ATTR_VOL_SPACEFREE
-as
-.Fa f_bavail
-is to
-.Fa f_bfree
-in
+.Dv ATTR_VOL_SPACEAVAIL
+is to
+.Dv ATTR_VOL_SPACEFREE
+as
+.Fa f_bavail
+is to
+.Fa f_bfree
+in
.Xr statfs 2 .
.
.It ATTR_VOL_MINALLOCATION
-An
+An
.Vt off_t
-containing the minimum allocation size on the volume in bytes.
+containing the minimum allocation size on the volume in bytes.
If you create a file containing one byte, it will consume this much space.
.
.It ATTR_VOL_ALLOCATIONCLUMP
-An
+An
.Vt off_t
-containing the allocation clump size on the volume, in bytes.
-As a file is extended, the file system will attempt to allocate
+containing the allocation clump size on the volume, in bytes.
+As a file is extended, the file system will attempt to allocate
this much space each time in order to reduce fragmentation.
.
.It ATTR_VOL_IOBLOCKSIZE
-A
-.Vt unsigned long
-containing the optimal block size when reading or writing data.
-Equivalent to the
-.Fa f_iosize
-field of the
-.Vt statfs
-structure returned by
+A
+.Vt u_int32_t
+containing the optimal block size when reading or writing data.
+Equivalent to the
+.Fa f_iosize
+field of the
+.Vt statfs
+structure returned by
.Xr statfs 2 .
.
.It ATTR_VOL_OBJCOUNT
-A
-.Vt unsigned long
+A
+.Vt u_int32_t
containing the number of file system objects on the volume.
.
.It ATTR_VOL_FILECOUNT
-A
-.Vt unsigned long
+A
+.Vt u_int32_t
containing the number of files on the volume.
.
.It ATTR_VOL_DIRCOUNT
-A
-.Vt unsigned long
+A
+.Vt u_int32_t
containing the number of directories on the volume.
.
.It ATTR_VOL_MAXOBJCOUNT
-A
-.Vt unsigned long
+A
+.Vt u_int32_t
containing the maximum number of file system objects that can be stored on the volume.
.
.It ATTR_VOL_MOUNTPOINT
-An
+An
.Vt attrreference
-structure containing the path to the volume's mount point as a
+structure containing the path to the volume's mount point as a
UTF-8 encoded, null terminated C string.
-The attribute data length will not be greater than
+The attribute data length will not be greater than
.Dv MAXPATHLEN .
-Equivalent to the
-.Fa f_mntonname
-field of the
-.Vt statfs
-structure returned by
+Equivalent to the
+.Fa f_mntonname
+field of the
+.Vt statfs
+structure returned by
.Xr statfs 2 .
.
.It ATTR_VOL_NAME
-(read/write) An
+(read/write) An
.Vt attrreference
-structure containing the name of the volume as a
+structure containing the name of the volume as a
UTF-8 encoded, null terminated C string.
-The attribute data length will not be greater than
+The attribute data length will not be greater than
.Dv NAME_MAX +
1.
.Pp
.
-This attribute is only read/write if the
+This attribute is only read/write if the
.Dv VOL_CAP_INT_VOL_RENAME
bit is set in the volume capabilities (see below).
.Pp
.
.It ATTR_VOL_MOUNTFLAGS
-A
-.Vt unsigned long
-containing the volume mount flags.
-This is a copy of the value passed to the
+A
+.Vt u_int32_t
+containing the volume mount flags.
+This is a copy of the value passed to the
.Fa flags
-parameter of
+parameter of
.Xr mount 2
when the volume was mounted.
-Equivalent to the
-.Fa f_flags
-field of the
-.Vt statfs
-structure returned by
+Equivalent to the
+.Fa f_flags
+field of the
+.Vt statfs
+structure returned by
.Xr statfs 2 .
.
.It ATTR_VOL_MOUNTEDDEVICE
-An
+An
.Vt attrreference
-structure that returns the same value as the
-.Fa f_mntfromname
-field of the
-.Vt statfs
-structure returned by
+structure that returns the same value as the
+.Fa f_mntfromname
+field of the
+.Vt statfs
+structure returned by
.Xr statfs 2 .
-For local volumes this is the path to the device on which the volume is mounted as a
+For local volumes this is the path to the device on which the volume is mounted as a
UTF-8 encoded, null terminated C string.
For network volumes, this is a unique string that identifies the mount.
-The attribute data length will not be greater than
+The attribute data length will not be greater than
.Dv MAXPATHLEN .
.Pp
.
.It ATTR_VOL_ENCODINGSUSED
-An
+An
.Vt unsigned long long
-containing a bitmap of the text encodings used on this volume.
-For more information about this, see the discussion of
-.Fa encodingsBitmap
+containing a bitmap of the text encodings used on this volume.
+For more information about this, see the discussion of
+.Fa encodingsBitmap
in DTS Technote 1150 "HFS Plus Volume Format".
.
.It ATTR_VOL_CAPABILITIES
A
.Vt vol_capabilities_attr_t
-structure describing the optional features supported by this volume.
+structure describing the optional features supported by this volume.
See below for a discussion of volume capabilities.
.
+.It ATTR_VOL_UUID
+A
+.Vt uuid_t
+containing the file system UUID. Typically this will be a
+version 5 UUID.
+.
+.It ATTR_VOL_QUOTA_SIZE
+An
+.Vt off_t
+containing the maximum size of the volume in bytes.
+.
+.It ATTR_VOL_RESERVED_SIZE
+An
+.Vt off_t
+containing the minimum size of the volume in bytes.
+.
.It ATTR_VOL_ATTRIBUTES
A
.Vt vol_attributes_attr_t
-structure describing the attributes supported by this volume.
+structure describing the attributes supported by this volume.
This structure is discussed below, along with volume capabilities.
.
.El
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
.It ATTR_DIR_LINKCOUNT
-A
-.Vt unsigned long
-containing the number of file system objects in the directory, including
-synthetic items such as "." and "..".
-For historical reasons, you should not always rely on this value being accurate.
-.Pp
-If you're implementing a volume format on which this is hard to calculate,
-you should not support this attribute.
-While it's traditional to return a constant value of 1 in the
-.Fa st_nlink
-field of the
-.Vt stat
-structure as returned by
-.Xr stat 2 ,
-it's not necessary to do this here because there is a
-defined way to indicate that you do not support the attribute.
+A
+.Vt u_int32_t
+containing the number of hard links to the directory;
+this does not include the historical "." and ".." entries.
+For file systems that do not support hard links to directories,
+this value will be 1.
.
.It ATTR_DIR_ENTRYCOUNT
-A
-.Vt unsigned long
-containing the number of file system objects in the directory, not including
-any synthetic items.
+A
+.Vt u_int32_t
+containing the number of file system objects in the directory, not including
+any synthetic items. The historical "." and ".." entries are also
+excluded from this count.
.
.It ATTR_DIR_MOUNTSTATUS
-A
-.Vt unsigned long
-containing flags describing what's mounted on the directory.
-Currently the only flag defined is
-.Dv DIR_MNTSTATUS_MNTPOINT,
+A
+.Vt u_int32_t
+containing flags describing what's mounted on the directory.
+Currently the only flag defined is
+.Dv DIR_MNTSTATUS_MNTPOINT,
which indicates that there is a file system mounted on this directory.
-Due to a bug (r. 3502822), this flag is never set on current system.
.
+.It ATTR_DIR_ALLOCSIZE
+An
+.Vt off_t
+containing the number of bytes on disk used by the directory
+(the physical size).
+.
+.It ATTR_DIR_IOBLOCKSIZE
+A
+.Vt u_int32_t
+containing the optimal block size when reading or writing data.
+.
+.It ATTR_DIR_DATALENGTH
+An
+.Vt off_t
+containing the length of the directory in bytes (the logical size).
.El
.
+.Pp
+Requested directory attributes are not returned for file system objects that
+are not directories.
+.
.Sh FILE ATTRIBUTES
.
The following file attributes are defined.
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
.It ATTR_FILE_LINKCOUNT
-A
-.Vt unsigned long
-containing the number of hard links to this file.
-Equivalent to the
-.Fa st_nlink
-field of the
-.Vt stat
-structure returned by
+A
+.Vt u_int32_t
+containing the number of hard links to this file.
+Equivalent to the
+.Fa st_nlink
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_FILE_TOTALSIZE
-An
+An
.Vt off_t
containing the total number of bytes in all forks of the file (the logical size).
.
.It ATTR_FILE_ALLOCSIZE
-An
+An
.Vt off_t
containing a count of the bytes on disk used by all of the file's forks (the physical size).
.
.It ATTR_FILE_IOBLOCKSIZE
-A
-.Vt unsigned long
-containing the optimal block size when reading or writing this file's data.
+A
+.Vt u_int32_t
+containing the optimal block size when reading or writing this file's data.
.
.It ATTR_FILE_CLUMPSIZE
-A
-.Vt unsigned long
-containing the allocation clump size for this file, in bytes.
-As the file is extended, the file system will attempt to allocate
-this much space each time in order to reduce fragmentation.
+A
+.Vt u_int32_t
+containing the allocation clump size for this file, in bytes.
+As the file is extended, the file system will attempt to allocate
+this much space each time in order to reduce fragmentation.
This value applies to the data fork.
.
.It ATTR_FILE_DEVTYPE
-(read/write) A
-.Vt unsigned long
-containing the device type for a special device file.
-Equivalent to the
-.Fa st_rdev
-field of the
-.Vt stat
-structure returned by
+(read/write) A
+.Vt u_int32_t
+containing the device type for a special device file.
+Equivalent to the
+.Fa st_rdev
+field of the
+.Vt stat
+structure returned by
.Xr stat 2 .
.
.It ATTR_FILE_FILETYPE
A
-.Vt unsigned long
+.Vt u_int32_t
that whose value is reserved.
Clients should ignore its value.
New volume format implementations should not support this attribute.
.
.It ATTR_FILE_FORKCOUNT
A
-.Vt unsigned long
+.Vt u_int32_t
containing the number of forks in the file.
-No built-in file systems on Mac OS X currently support forks other
+No built-in file systems on Mac OS X currently support forks other
than the data and resource fork.
.
.It ATTR_FILE_FORKLIST
-An
+An
.Vt attrreference
structure containing a list of named forks of the file.
-No built-in file systems on Mac OS X currently support forks
+No built-in file systems on Mac OS X currently support forks
other than the data and resource fork.
Because of this, the structure of this attribute's value is not yet defined.
.
.It ATTR_FILE_DATAEXTENTS
An
.Vt extentrecord
-array for the data fork.
-The array contains eight
-.Vt diskextent
-structures which represent the first
+array for the data fork.
+The array contains eight
+.Vt diskextent
+structures which represent the first
eight extents of the fork.
.Pp
-This attributes exists for compatibility reasons.
+This attributes exists for compatibility reasons.
New clients should not use this attribute.
-Rather, they should use the
-.Dv F_LOG2PHYS
-command in
+Rather, they should use the
+.Dv F_LOG2PHYS
+command in
.Xr fcntl 2 .
.Pp
.
-In current implementations the value may not be entirely accurate for
+In current implementations the value may not be entirely accurate for
a variety of reasons.
.
.It ATTR_FILE_RSRCLENGTH
.It ATTR_FILE_RSRCEXTENTS
An
.Vt extentrecord
-array for the resource fork.
-The array contains eight
-.Vt diskextent
-structures which represent the first
+array for the resource fork.
+The array contains eight
+.Vt diskextent
+structures which represent the first
eight extents of the fork.
.Pp
-See also
+See also
.Dv ATTR_FILE_DATAEXTENTS .
.
.El
.
+.Pp
+File attributes are used for any file system object that is not a directory,
+not just ordinary files.
+Requested file attributes are not returned for file system objects that
+are directories.
+.
.Sh FORK ATTRIBUTES
.
-Fork attributes relate to the actual data in the file,
+Fork attributes relate to the actual data in the file,
which can be held in multiple named contiguous ranges, or forks.
+These cannot be used if the FSOPT_ATTR_CMN_EXTENDED is given.
The following fork attributes are defined.
.
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
.It ATTR_FORK_TOTALSIZE
+Deprecated.
An
.Vt off_t
containing the length of the fork in bytes (the logical size).
.
.It ATTR_FORK_ALLOCSIZE
+Deprecated.
An
.Vt off_t
containing a count of the bytes on disk used by the fork (the physical size).
.
+.It ATTR_FORK_RESERVED
+Reserved.
+You must set this to 0.
+.
.El
.Pp
.
-Fork attributes are not properly implemented by any current Mac OS X
-volume format implementation.
-We strongly recommend that client programs do not request fork attributes.
-If you are implementing a volume format, you should not support these attributes.
+Fork attributes are deprecated and all bits are reserved.
+They are not properly implemented by any current Mac OS X
+volume format implementation.
+We strongly recommend that client programs do not request fork attributes.
+If you are implementing a volume format, you should not support these attributes.
+.
+.Sh COMMON EXTENDED ATTRIBUTES
+.
+Common extended attributes are like common attributes except that they are set
+in the forkattr field and can only be used if the FSOPT_ATTR_CMN_EXTENDED
+option is given. Use of these attributes is mutually exclusive with the above
+fork attributes.
+.
+.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
+.
+.It ATTR_CMNEXT_RELPATH
+An
+.Vt attrreference
+structure containing the mount-relative path of
+the file system object as
+a UTF-8 encoded, null terminated C string.
+The attribute data length will not be greater than
+.Dv PATH_MAX.
+Inconsistent behavior may be observed when this attribute is requested on
+hard-linked items, particularly when the file system does not support
+ATTR_CMN_PARENTID natively. Callers should be aware of this when requesting the
+relative path of a hard-linked item.
+.
+.It ATTR_CMNEXT_PRIVATESIZE
+An
+.Vt off_t
+containing the number of bytes that are \fBnot\fP trapped inside a clone
+or snapshot, and which would be freed immediately if the file were deleted.
+.
+.It ATTR_CMNEXT_LINKID
+A
+.Vt u_int64_t
+that uniquely identifies the file system object within a mounted volume for the
+duration of its mount.
+.Pp
+On HFS+ and APFS volumes, the ATTR_CMNEXT_LINKID of a file system
+object is distinct from the ATTR_CMNEXT_LINKID of any hard link to that file
+system object. Although the ATTR_CMNEXT_LINKID of a file system object may appear
+similar (in whole or in part) to its ATTR_CMN_FILEID (see description of
+ATTR_CMN_FILEID above), \fBno relation between the two attributes should ever be implied.\fP
+.
+.El
.
.Sh VOLUME CAPABILITIES
.
.\" vol_capabilities_attr_t
.
-Not all volumes support all features. The
-.Dv ATTR_VOL_CAPABILITIES
-attribute returns a
-.Vt vol_capabilities_attr_t
+Not all volumes support all features.
+The
+.Dv ATTR_VOL_CAPABILITIES
+attribute returns a
+.Vt vol_capabilities_attr_t
structure (shown below) that indicates which features are supported by the volume.
.
.Bd -literal
.Ed
.Pp
.
-The structure contains two fields,
-.Fa capabilities
-and
+The structure contains two fields,
+.Fa capabilities
+and
.Fa valid .
-Each consists of an array of four elements.
+Each consists of an array of four elements.
The arrays are indexed by the following values.
.
.Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
.
.It VOL_CAPABILITIES_FORMAT
-This element contains information about the volume format.
-See
-.Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
+This element contains information about the volume format.
+See
+.Dv VOL_CAP_FMT_PERSISTENTOBJECTIDS
and so on, below.
.
.It VOL_CAPABILITIES_INTERFACES
-This element contains information about which optional functions are
+This element contains information about which optional functions are
supported by the volume format implementation.
-See
-.Dv VOL_CAP_INT_SEARCHFS
+See
+.Dv VOL_CAP_INT_SEARCHFS
and so on, below.
.
.It VOL_CAPABILITIES_RESERVED1
-Reserved.
-A file system implementation should set this element to zero.
+Reserved.
+A file system implementation should set this element to zero.
A client program should ignore this element.
.
.It VOL_CAPABILITIES_RESERVED2
-Reserved.
-A file system implementation should set this element to zero.
+Reserved.
+A file system implementation should set this element to zero.
A client program should ignore this element.
.
.El
.Pp
.
-The
-.Fa valid
-field contains bit sets that indicate which flags are known to the volume format
-implementation.
-Each bit indicates whether the contents of the corresponding bit in the
-.Fa capabilities
+The
+.Fa valid
+field contains bit sets that indicate which flags are known to the volume format
+implementation.
+Each bit indicates whether the contents of the corresponding bit in the
+.Fa capabilities
field is valid.
.Pp
.
-The
-.Fa capabilities
-field contains bit sets that indicate whether a particular feature is implemented
-by this volume format.
+The
+.Fa capabilities
+field contains bit sets that indicate whether a particular feature is implemented
+by this volume format.
.Pp
.
-The following bits are defined in the first element (indexed by
-.Dv VOL_CAPABILITIES_FORMAT )
-of the
-.Fa capabilities
-and
-.Fa valid
-fields of the
-.Vt vol_capabilities_attr_t
+The following bits are defined in the first element (indexed by
+.Dv VOL_CAPABILITIES_FORMAT )
+of the
+.Fa capabilities
+and
+.Fa valid
+fields of the
+.Vt vol_capabilities_attr_t
structure.
.
.Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
.
.It VOL_CAP_FMT_PERSISTENTOBJECTIDS
-If this bit is set the volume format supports persistent object identifiers
+If this bit is set the volume format supports persistent object identifiers
and can look up file system objects by their IDs.
-See
-.Dv ATTR_CMN_OBJPERMANENTID
+See
+.Dv ATTR_CMN_OBJPERMANENTID
for details about how to obtain these identifiers.
.
.It VOL_CAP_FMT_SYMBOLICLINKS
-If this bit is set the volume format supports symbolic links.
+If this bit is set the volume format supports symbolic links.
.
.It VOL_CAP_FMT_HARDLINKS
-If this bit is set the volume format supports hard links.
+If this bit is set the volume format supports hard links.
.
.It VOL_CAP_FMT_JOURNAL
-If this bit is set the volume format supports a journal used to
-speed recovery in case of unplanned restart (such as a power outage
+If this bit is set the volume format supports a journal used to
+speed recovery in case of unplanned restart (such as a power outage
or crash).
This does not necessarily mean the volume is actively using a journal.
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_JOURNAL_ACTIVE
-If this bit is set the volume is currently using a journal for
+If this bit is set the volume is currently using a journal for
speedy recovery after an unplanned restart.
-This bit can be set only if
+This bit can be set only if
.Dv VOL_CAP_FMT_JOURNAL
is also set.
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_NO_ROOT_TIMES
-If this bit is set the volume format does not store reliable times for
-the root directory, so you should not depend on them to detect changes,
+If this bit is set the volume format does not store reliable times for
+the root directory, so you should not depend on them to detect changes,
identify volumes across unmount/mount, and so on.
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.It VOL_CAP_FMT_SPARSE_FILES
If this bit is set the volume format supports sparse files,
that is, files which can have 'holes' that have never been written
-to, and thus do not consume space on disk.
+to, and thus do not consume space on disk.
A sparse file may have an allocated size on disk that is less than its logical length (that is,
-.Dv ATTR_FILE_ALLOCSIZE
+.Dv ATTR_FILE_ALLOCSIZE
<
.Dv ATTR_FILE_TOTALSIZE ).
.
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_ZERO_RUNS
-For security reasons, parts of a file (runs) that have never been
-written to must appear to contain zeroes.
+For security reasons, parts of a file (runs) that have never been
+written to must appear to contain zeroes.
When this bit is set, the volume keeps track of allocated but unwritten
runs of a file so that it can substitute zeroes without actually
-writing zeroes to the media.
+writing zeroes to the media.
This provides performance similar to sparse files, but not the space savings.
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_CASE_SENSITIVE
-If this bit is set the volume format treats upper and lower case
-characters in file and directory names as different.
-Otherwise an upper case character is equivalent to a lower case character,
+If this bit is set the volume format treats upper and lower case
+characters in file and directory names as different.
+Otherwise an upper case character is equivalent to a lower case character,
and you can't have two names that differ solely in the case of
the characters.
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_CASE_PRESERVING
-If this bit is set the volume format preserves the case of
-file and directory names.
-Otherwise the volume may change the case of some characters
+If this bit is set the volume format preserves the case of
+file and directory names.
+Otherwise the volume may change the case of some characters
(typically making them all upper or all lower case).
-A volume that sets
+A volume that sets
.Dv VOL_CAP_FMT_CASE_SENSITIVE
-must also set
+must also set
.Dv VOL_CAP_FMT_CASE_PRESERVING .
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_FAST_STATFS
-This bit is used as a hint to upper layers (specifically the Carbon File Manager) to
-indicate that
+This bit is used as a hint to upper layers to
+indicate that
+.Xr statfs 2
+is fast enough that its results need not be cached by the caller.
+A volume format implementation that caches the
.Xr statfs 2
-is fast enough that its results need not be cached by the caller.
-A volume format implementation that caches the
-.Xr statfs 2
information in memory should set this bit.
-An implementation that must always read from disk or always perform a network
-transaction to satisfy
+An implementation that must always read from disk or always perform a network
+transaction to satisfy
.Xr statfs 2
should not set this bit.
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_FMT_2TB_FILESIZE
-If this bit is set the volume format supports file
-sizes upto 2TB. This bit does not necessarily mean that the file
-system does not support file size more than 2TB. This bit does
-not mean that the currently available space on the volume is 2TB.
+If this bit is set the volume format supports file sizes larger
+than 4GB, and potentially up to 2TB; it does not indicate
+whether the file system supports files larger than that.
.Pp
Introduced with Darwin 8.0 (Mac OS X version 10.4).
.
+.It VOL_CAP_FMT_OPENDENYMODES
+If this bit is set, the volume format supports open deny modes
+(e.g., "open for read write, deny write").
+.
+.It VOL_CAP_FMT_HIDDEN_FILES
+If this bit is set, the volume format supports the
+.Dv UF_HIDDEN
+file flag, and the
+.Dv UF_HIDDEN
+flag is mapped to that volume's native "hidden" or "invisible"
+bit (e.g., the invisible bit from the Finder Info extended attribute).
+.
+.It VOL_CAP_FMT_PATH_FROM_ID
+If this bit is set, the volume format supports the ability to derive a pathname
+to the root of the file system given only the ID of an object. This also
+implies that object IDs on this file system are persistent and not recycled.
+Most file systems will not support this capability.
+.
+.It VOL_CAP_FMT_NO_VOLUME_SIZES
+If this bit is set the volume format does not support
+determining values for total data blocks, available blocks, or free blocks, as in
+.Fa f_blocks,
+.Fa f_bavail,
+and
+.Fa f_bfree
+in the
+.Fa struct statfs
+returned by
+.Xr statfs 2 .
+Historically, those values were set to 0xFFFFFFFF for volumes
+that did not support them.
+.Pp
+Introduced with Darwin 10.0 (Mac OS X version 10.6).
+.
+.It VOL_CAP_FMT_64BIT_OBJECT_IDS
+If this bit is set, the volume format uses object IDs that are 64-bit.
+This means that ATTR_CMN_FILEID and ATTR_CMN_PARENTID are the primary means of
+obtaining object IDs from this volume. The values returned by ATTR_CMN_OBJID,
+ATTR_CMN_OBJPERMANENTID, and ATTR_CMN_PAROBJID can be interpreted as 64-bit
+object IDs instead of fsobj_id_t.
+.
+.It VOL_CAP_FMT_NO_IMMUTABLE_FILES
+If this bit is set, the volume format does not support setting the UF_IMMUTABLE
+flag.
+See ATTR_CMN_FLAGS for more details.
+.It VOL_CAP_FMT_NO_PERMISSIONS
+If this bit is set, the volume format does not support setting file
+permissions.
+See ATTR_CMN_USERACCESS for more details.
+.
.El
.Pp
.
-The following bits are defined in the second element (indexed by
-.Dv VOL_CAPABILITIES_INTERFACES )
-of the
-.Fa capabilities
-and
-.Fa valid
-fields of the
-.Vt vol_capabilities_attr_t
+The following bits are defined in the second element (indexed by
+.Dv VOL_CAPABILITIES_INTERFACES )
+of the
+.Fa capabilities
+and
+.Fa valid
+fields of the
+.Vt vol_capabilities_attr_t
structure.
.
.Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
.
.It VOL_CAP_INT_SEARCHFS
-If this bit is set the volume format implementation supports
+If this bit is set the volume format implementation supports
.Xr searchfs 2 .
.
.It VOL_CAP_INT_ATTRLIST
-If this bit is set the volume format implementation supports
-.Fn getattrlist
-and
+If this bit is set the volume format implementation supports
+.Fn getattrlist
+and
.Xr setattrlist 2 .
.
.It VOL_CAP_INT_NFSEXPORT
-If this bit is set the volume format implementation allows this volume to be exported via NFS.
+If this bit is set the volume format implementation allows this volume to be exported via NFS.
.
.It VOL_CAP_INT_READDIRATTR
-If this bit is set the volume format implementation supports
+If this bit is set the volume format implementation supports
.Xr getdirentriesattr 2 .
.
.It VOL_CAP_INT_EXCHANGEDATA
-If this bit is set the volume format implementation supports
+If this bit is set the volume format implementation supports
.Xr exchangedata 2 .
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.It VOL_CAP_INT_COPYFILE
If this bit is set the volume format implementation supports the (private and undocumented)
copyfile() function.
+(This is not the
+.Xr copyfile 3
+function.)
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_INT_ALLOCATE
-If this bit is set the volume format implementation supports the
-.Dv F_PREALLOCATE
-selector of
+If this bit is set the volume format implementation supports the
+.Dv F_PREALLOCATE
+selector of
.Xr fcntl 2 .
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_INT_VOL_RENAME
-If this bit is set the volume format implementation allows you to
-modify the volume name using
+If this bit is set the volume format implementation allows you to
+modify the volume name using
.Xr setattrlist 2 .
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_INT_ADVLOCK
-If this bit is set the volume format implementation supports
-advisory locking, that is, the
+If this bit is set the volume format implementation supports
+advisory locking, that is, the
.Dv F_GETLK ,
-.Dv F_SETLK ,
-and
-.Dv F_SETLKW
-selectors to
+.Dv F_SETLK ,
+and
+.Dv F_SETLKW
+selectors to
.Xr fcntl 2 .
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
.It VOL_CAP_INT_FLOCK
-If this bit is set the volume format implementation supports
-whole file locks.
-This includes
-.Xr flock 2
-and the
-.Dv O_EXLOCK
-and
-.Dv O_SHLOCK
-flags to
+If this bit is set the volume format implementation supports
+whole file locks.
+This includes
+.Xr flock 2
+and the
+.Dv O_EXLOCK
+and
+.Dv O_SHLOCK
+flags to
.Xr open 2 .
.Pp
Introduced with Darwin 7.0 (Mac OS X version 10.3).
.
+.It VOL_CAP_INT_EXTENDED_SECURITY
+If this bit is set the volume format implementation supports
+extended security controls (ACLs).
+.Pp
+Introduced with Darwin 8.0 (Mac OS X version 10.4).
+.
+.It VOL_CAP_INT_USERACCESS
+If this bit is set the volume format implementation supports the
+ATTR_CMN_USERACCESS attribute.
+.Pp
+Introduced with Darwin 8.0 (Mac OS X version 10.4).
+.
+.It VOL_CAP_INT_MANLOCK
+If this bit is set, the volume format implementation supports
+AFP-style mandatory byte range locks via
+.Xr ioctl 2 .
+.
+.It VOL_CAP_INT_EXTENDED_ATTR
+If this bit is set, the volume format implementation supports
+native extended attributes (see
+.Xr setxattr 2 Ns ).
+.
+.It VOL_CAP_INT_CLONE
+If this bit is set, the file system supports cloning files and directories.
+See
+.Xr clonefileat 2
+for more details.
+.
+.It VOL_CAP_INT_SNAPSHOT
+If this bit is set, the file system supports snapshots.
+See
+.Xr fs_snapshot_create 2
+for more details.
+.
+.It VOL_CAP_INT_NAMEDSTREAMS
+If this bit is set, the volume format implementation supports
+native named streams.
+.
+.It VOL_CAP_INT_RENAME_SWAP
+If this bit is set, the file system supports swapping file system
+objects. See
+.Xr rename 2
+for more details.
+.
+.It VOL_CAP_INT_RENAME_EXCL
+If this bit is set, the file system supports an exclusive rename
+operation. See
+.Xr rename 2
+for more details.
+.
.El
.Pp
.
.\" vol_attributes_attr_t
.
-A volume can also report which attributes it supports.
+A volume can also report which attributes it supports.
This information is returned by the
-.Dv ATTR_VOL_ATTRIBUTES
-attribute, which returns a
-.Vt vol_attributes_attr_t
+.Dv ATTR_VOL_ATTRIBUTES
+attribute, which returns a
+.Vt vol_attributes_attr_t
structure (shown below).
.
.Bd -literal
.Ed
.Pp
.
-The
-.Fa validattr
-field consists of a number of bit sets that indicate whether an attribute is
-supported by the volume format implementation.
-The
-.Fa nativeattr
-is similar except that the bit sets indicate whether an attribute is supported
-natively by the volume format.
-An attribute is supported natively if the volume format implementation does not have to do
-any complex conversions to access the attribute.
-For example, a volume format might support persistent object identifiers, but
-doing so requires a complex table lookup that is not part of the core volume
-format.
-In that case, the
-.Dv ATTR_VOL_ATTRIBUTES
-attribute would return
-.Dv ATTR_CMN_OBJPERMANENTID
-set in the
-.Fa validattr
-field of the
+The
+.Fa validattr
+field consists of a number of bit sets that indicate whether an attribute is
+supported by the volume format implementation.
+The
+.Fa nativeattr
+is similar except that the bit sets indicate whether an attribute is supported
+natively by the volume format.
+An attribute is supported natively if the volume format implementation does not have to do
+any complex conversions to access the attribute.
+For example, a volume format might support persistent object identifiers, but
+doing so requires a complex table lookup that is not part of the core volume
+format.
+In that case, the
+.Dv ATTR_VOL_ATTRIBUTES
+attribute would return
+.Dv ATTR_CMN_OBJPERMANENTID
+set in the
+.Fa validattr
+field of the
.Vt vol_attributes_attr_t ,
-but not in the
-.Fa nativeattr
+but not in the
+.Fa nativeattr
field.
.
.Sh RETURN VALUES
is set to indicate the error.
.
.Sh COMPATIBILITY
-Not all volumes support
+Not all volumes support
.Fn getattrlist .
-The best way to test whether a volume supports this function is to
+The best way to test whether a volume supports this function is to
simply call it and check the error result.
-.Fn getattrlist
-will return
+.Fn getattrlist
+will return
.Dv ENOTSUP
if it is not supported on a particular volume.
.Pp
.
-The
-.Fn getattrlist
-function has been undocumented for more than two years.
-In that time a number of volume format implementations have been created without
-a proper specification for the behaviour of this routine.
-You may encounter volume format implementations with slightly different
-behaviour than what is described here.
+The
+.Fn getattrlist
+function has been undocumented for more than two years.
+In that time a number of volume format implementations have been created without
+a proper specification for the behaviour of this routine.
+You may encounter volume format implementations with slightly different
+behaviour than what is described here.
Your program is expected to be tolerant of this variant behaviour.
.Pp
.
-If you're implementing a volume format that supports
+If you're implementing a volume format that supports
.Fn getattrlist ,
you should be careful to support the behaviour specified by this document.
.
.Sh ERRORS
.Fn getattrlist
+and
+.Fn fgetattrlist
will fail if:
.Bl -tag -width Er
.
.It Bq Er ENOTSUP
-The volume does not support
-.Fn getattrlist .
+The volume does not support the query.
.
.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+A component of the path prefix for
+.Fn getattrlist
+is not a directory.
.
.It Bq Er ENAMETOOLONG
-A component of a path name exceeded
+A component of a path name for
+.Fn getattrlist
+exceeded
.Dv NAME_MAX
-characters, or an entire path name exceeded
+characters, or an entire path name exceeded
.Dv PATH_MAX
characters.
.
.It Bq Er ENOENT
-The file system object does not exist.
+The file system object for
+.Fn getattrlist
+does not exist.
+.
+.It Bq Er EBADF
+The file descriptor argument for
+.Fn fgetattrlist
+is not a valid file descriptor.
.
.It Bq Er EACCES
-Search permission is denied for a component of the path prefix.
+Search permission is denied for a component of the path prefix for
+.Fn getattrlist .
.
.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+Too many symbolic links were encountered in translating the pathname
+for
+.Fn getattrlist .
.
.It Bq Er EFAULT
.Fa path ,
points to an invalid address.
.
.It Bq Er EINVAL
-The
-.Fa bitmapcount
-field of
-.Fa attrList
-is not
+The
+.Fa bitmapcount
+field of
+.Fa attrList
+is not
.Dv ATTR_BIT_MAP_COUNT .
.
.It Bq Er EINVAL
You requested volume attributes and directory or file attributes.
.
.It Bq Er EINVAL
-You requested volume attributes but
-.Fa path
+You requested volume attributes but
+.Fa path
does not reference the root of the volume.
.
.It Bq Er EROFS
An I/O error occurred while reading from or writing to the file system.
.El
.Pp
+In addition to the errors returned by the
+.Fn getattrlist ,
+the
+.Fn getattrlistat
+function may fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
+.El
+.Pp
.
.Sh CAVEATS
.
-If you request any volume attributes, you must set
-.Dv ATTR_VOL_INFO
-in the
+If you request any volume attributes, you must set
+.Dv ATTR_VOL_INFO
+in the
.Fa volattr
field, even though it generates no result in the attribute buffer.
.Pp
.
-The order that attributes are stored in the attribute buffer almost
+The order that attributes are stored in the attribute buffer almost
invariably matches the order of attribute mask bit values.
-For example,
-.Dv ATTR_CMN_NAME
-(0x00000001) comes before
-.Dv ATTR_CMN_DEVID
+For example,
+.Dv ATTR_CMN_NAME
+(0x00000001) comes before
+.Dv ATTR_CMN_DEVID
(0x00000002) because its value is smaller.
-However, you can not rely on this ordering because there is one key exception:
-.Dv ATTR_CMN_FLAGS
-is placed after the
-.Dv ATTR_CMN_NAMEDATTRCOUNT
-/
-.Dv ATTR_CMN_NAMEDATTRLIST
-pair, even though its bit position indicates that it should come before.
-This is due to a bug in an early version of Mac OS X that can't be fixed for
-binary compatibility reasons.
-When ordering attributes, you should always use the order in which they
+When ordering attributes, you should always use the order in which they
are described above.
.Pp
.
+The
+.Vt timespec
+structure is 64-bits (two 32-bit elements) in 32-bit code, and
+128-bits (two 64-bit elements) in 64-bit code; however, it is aligned
+on a 4-byte (32-bit) boundary, even in 64-bit code.
+.Pp
+If you use a structure
+for the attribute data, it must be correctly packed and aligned (see
+examples).
+.Pp
+.
+Inconsistent behavior may be observed when the ATTR_CMN_FULLPATH attribute is requested on
+hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
+natively. Callers should be aware of this when requesting the full path of a hard-linked item, especially
+if the full path crosses mount points.
+.Pp
+.
For more caveats, see also the compatibility notes above.
.
.Sh EXAMPLES
.
-The following code prints the file type and creator of a file,
+The following code prints the file type and creator of a file,
assuming that the volume supports the required attributes.
.
.Bd -literal
.Pp
.
struct FInfoAttrBuf {
- unsigned long length;
+ u_int32_t length;
fsobj_type_t objType;
char finderInfo[32];
-};
+} __attribute__((aligned(4), packed));
typedef struct FInfoAttrBuf FInfoAttrBuf;
.Pp
.
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
.Pp
-
+
err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
if (err != 0) {
err = errno;
}
.Pp
-
+
if (err == 0) {
assert(attrBuf.length == sizeof(attrBuf));
.Pp
-
+
printf("Finder information for %s:\en", path);
switch (attrBuf.objType) {
case VREG:
.Ed
.Pp
.
-The following code is an alternative implementation that uses nested structures
+The following code is an alternative implementation that uses nested structures
to group the related attributes.
.
.Bd -literal
struct FInfo2CommonAttrBuf {
fsobj_type_t objType;
char finderInfo[32];
-};
+} __attribute__((aligned(4), packed));
typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
.Pp
.
struct FInfo2AttrBuf {
- unsigned long length;
+ u_int32_t length;
FInfo2CommonAttrBuf common;
-};
+} __attribute__((aligned(4), packed));;
typedef struct FInfo2AttrBuf FInfo2AttrBuf;
.Pp
.
switch (attrBuf.common.objType) {
case VREG:
printf(
- "file type = '%.4s'\en",
+ "file type = '%.4s'\en",
&attrBuf.common.finderInfo[0]
);
printf(
- "file creator = '%.4s'\en",
+ "file creator = '%.4s'\en",
&attrBuf.common.finderInfo[4]
);
break;
break;
default:
printf(
- "other object type, %d\en",
+ "other object type, %d\en",
attrBuf.common.objType
);
break;
.Ed
.Pp
.
-The following example shows how to deal with variable length attributes.
-It assumes that the volume specified by
-.Fa path
+The following example shows how to deal with variable length attributes.
+It assumes that the volume specified by
+.Fa path
supports the necessary attributes.
.
.Bd -literal
.Pp
.
struct VolAttrBuf {
- unsigned long length;
- unsigned long fileCount;
- unsigned long dirCount;
+ u_int32_t length;
+ u_int32_t fileCount;
+ u_int32_t dirCount;
attrreference_t mountPointRef;
attrreference_t volNameRef;
char mountPointSpace[MAXPATHLEN];
char volNameSpace[MAXPATHLEN];
-};
+} __attribute__((aligned(4), packed));
typedef struct VolAttrBuf VolAttrBuf;
.Pp
.
.
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
- attrList.volattr = ATTR_VOL_INFO
- | ATTR_VOL_FILECOUNT
- | ATTR_VOL_DIRCOUNT
- | ATTR_VOL_MOUNTPOINT
+ attrList.volattr = ATTR_VOL_INFO
+ | ATTR_VOL_FILECOUNT
+ | ATTR_VOL_DIRCOUNT
+ | ATTR_VOL_MOUNTPOINT
| ATTR_VOL_NAME;
.Pp
-
+
err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
if (err != 0) {
err = errno;
}
.Pp
-
+
if (err == 0) {
assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace));
assert(attrBuf.length <= sizeof(attrBuf));
.Pp
-
+
printf("Volume information for %s:\en", path);
- printf("ATTR_VOL_FILECOUNT: %lu\en", attrBuf.fileCount);
- printf("ATTR_VOL_DIRCOUNT: %lu\en", attrBuf.dirCount);
+ printf("ATTR_VOL_FILECOUNT: %u\en", attrBuf.fileCount);
+ printf("ATTR_VOL_DIRCOUNT: %u\en", attrBuf.dirCount);
printf(
- "ATTR_VOL_MOUNTPOINT: %.*s\en",
+ "ATTR_VOL_MOUNTPOINT: %.*s\en",
(int) attrBuf.mountPointRef.attr_length,
- ( ((char *) &attrBuf.mountPointRef)
+ ( ((char *) &attrBuf.mountPointRef)
+ attrBuf.mountPointRef.attr_dataoffset )
);
printf(
- "ATTR_VOL_NAME: %.*s\en",
+ "ATTR_VOL_NAME: %.*s\en",
(int) attrBuf.volNameRef.attr_length,
- ( ((char *) &attrBuf.volNameRef)
+ ( ((char *) &attrBuf.volNameRef)
+ attrBuf.volNameRef.attr_dataoffset )
);
}
}
.Ed
.Pp
+The following sample demonstrates the need to use packing and alignment
+controls; without the attribute, in 64-bit code, the fields of the structure are not
+placed at the locations that the kernel expects.
+.
+.Bd -literal
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <err.h>
+#include <time.h>
+#include <sys/attr.h>
+.Pp
+/* The alignment and packing attribute is necessary in 64-bit code */
+struct AttrListTimes {
+ u_int32_t length;
+ struct timespec st_crtime;
+ struct timespec st_modtime;
+} __attribute__((aligned(4), packed));
+.Pp
+main(int argc, char **argv)
+{
+ int rv;
+ int i;
+.Pp
+ for (i = 1; i < argc; i++) {
+ struct attrlist attrList;
+ struct AttrListTimes myStat = {0};
+ char *path = argv[i];
+.Pp
+ memset(&attrList, 0, sizeof(attrList));
+ attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
+ attrList.commonattr = ATTR_CMN_CRTIME |
+ ATTR_CMN_MODTIME;
+.Pp
+ rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);
+.Pp
+ if (rv == -1) {
+ warn("getattrlist(%s)", path);
+ continue;
+ }
+ printf("%s: Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
+ }
+ return 0;
+}
+.Ed
+.Pp
+ The getLinkIDInfo() function determines if ATTR_CMNEXT_LINKID and ATTR_CMN_OBJID
+ are valid to use on the file system specified by path.
+.
+.Bd -literal
+int getLinkIDInfo(const char *path, bool *cmnExtLinkIDValid, bool *cmnObjIDValid)
+{
+ int result;
+ struct statfs statfsBuf;
+ struct attrlist attrList;
+ struct volAttrsBuf {
+ u_int32_t length;
+ vol_capabilities_attr_t capabilities;
+ vol_attributes_attr_t attributes;
+ } __attribute__((aligned(4), packed));
+ struct volAttrsBuf volAttrs;
+.Pp
+ memset(&attrList, 0, sizeof(attrList));
+ attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
+ attrList.volattr = ATTR_VOL_INFO | ATTR_VOL_CAPABILITIES | ATTR_VOL_ATTRIBUTES;
+ // get the file system's mount point path for the input path
+ result = statfs(path, &statfsBuf);
+ if ( result == 0 ) {
+ // get the supported capabilities and attributes
+ result = getattrlist(statfsBuf.f_mntonname, &attrList, &volAttrs, sizeof(volAttrs), FSOPT_ATTR_CMN_EXTENDED);
+ if ( result == 0 ) {
+ if ( volAttrs.attributes.validattr.forkattr & ATTR_CMNEXT_LINKID ) {
+ // ATTR_CMNEXT_LINKID is available; do not use ATTR_CMN_OBJID
+ *cmnExtLinkIDValid = true;
+ *cmnObjIDValid = false;
+ }
+ else {
+ // ATTR_CMNEXT_LINKID is not available
+ cmnExtLinkIDValid = false;
+ // ATTR_CMN_OBJID can only be used if the file system does not use 64-bit object IDs
+ if ( (volAttrs.capabilities.capabilities[VOL_CAPABILITIES_FORMAT] & VOL_CAP_FMT_64BIT_OBJECT_IDS) && (volAttrs.capabilities.valid[VOL_CAPABILITIES_FORMAT] & VOL_CAP_FMT_64BIT_OBJECT_IDS) ) {
+ *cmnObjIDValid = false;
+ }
+ else {
+ *cmnObjIDValid = true;
+ }
+ }
+ }
+ }
+ if ( result != 0 ) {
+ *cmnExtLinkIDValid = *cmnObjIDValid = false;
+ }
+ return result;
+}
+.Ed
+.Pp
.
.Sh SEE ALSO
.
.Xr chflags 2 ,
.Xr exchangedata 2 ,
.Xr fcntl 2 ,
-.Xr getdirentriesattr 2 ,
+.Xr getattrlistbulk 2 ,
.Xr mount 2 ,
.Xr searchfs 2 ,
.Xr setattrlist 2 ,
.Xr statfs 2
.
.Sh HISTORY
-A
+A
.Fn getattrlist
function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
-.
+The
+.Fn getattrlistat
+function call appeared in OS X 10.10 .
projects / apple / xnu.git / blobdiff