xnu-7195.101.1.tar.gz

[apple/xnu.git] / bsd / man / man2 / getattrlist.2

.\" 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,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" 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 February 11, 2020
.Dt GETATTRLIST 2
.Os Darwin
.Sh NAME
.Nm getattrlist ,
.Nm fgetattrlist ,
.Nm getattrlistat
.Nd get file system attributes
.Sh SYNOPSIS
.Fd #include <sys/attr.h>
.Fd #include <unistd.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.
.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 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 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
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
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
.
.\" path parameter
.
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
searchable.
.Pp
.
.\" attrList parameter
.
The
.Fa 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.
.Bd -literal
typedef u_int32_t attrgroup_t;
.Pp
struct attrlist {
    u_short     bitmapcount; /* number of attr. bit sets in list */
    u_int16_t   reserved;    /* (to maintain 4-byte alignment) */
    attrgroup_t commonattr;  /* common attribute group */
    attrgroup_t volattr;     /* volume attribute group */
    attrgroup_t dirattr;     /* directory attribute group */
    attrgroup_t fileattr;    /* file attribute group */
    attrgroup_t forkattr;    /* fork attribute group */
};
#define ATTR_BIT_MAP_COUNT 5
.Ed
.Pp
.
.\" attrlist elements
.
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
.Dv ATTR_BIT_MAP_COUNT .
.
.It reserved
Reserved.
You must set this to 0.
.
.It commonattr
A bit set that specifies the common attributes that you require.
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,
.Fa path
must reference the root of a volume.
You must set ATTR_VOL_INFO in the volattr field if you request any 
other volume attributes.
In addition, you can't request volume attributes if you also request
file, directory, fork or extended common attributes.
In addition, you can't request volume attributes if you also request the common 
attributes ATTR_CMN_EXTENDED_SECURITY, ATTR_CMN_UUID, ATTR_CMN_GRPUUID, 
ATTR_CMN_FILEID, or ATTR_CMN_PARENTID.  
.
.It dirattr
A bit set that specifies the directory attributes that you require.
See below for a description of these attributes.
.
.It fileattr
A bit set that specifies the file attributes that you require.
See below for a description of these attributes.
.
.It forkattr
A bit set that specifies the fork attributes that you require.
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
.Xr setattrlist 2 .
.Pp
.
.\" attrBuf and attrBufSize parameters
.
The
.Fa attrBuf
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
requires a separate section (see below).
The initial contents of this buffer are ignored.
.Pp
.
.\" option parameter
.
The
.Fa options
parameter is a bit set that controls the behaviour of
the functions.
The following option bits are defined.
.
.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
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.
.
.It FSOPT_RETURN_REALDEV
If this is bit is set, then ATTR_CMN_DEVID and ATTR_CMN_FSID will return
the values corresponding to the physical volume they are on. When a
filesystem supports VOL_CAP_INT_VOLUME_GROUPS, it is possible that the
filesystem may return a common logical value for these attributes otherwise.
.
.El
.
.Sh ATTRIBUTE BUFFER
.
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 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).
.
.It
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
.Aq Pa sys/attr.h
(shown below).
.
.Bd -literal
typedef struct attrreference {
    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(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
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
.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
) ).
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
.
Common attributes relate to all types of file system objects.
The following common attributes are defined.
.
.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
UTF-8 encoded, null terminated C string.
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
file system object's volume is mounted.
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
the file system object resides.
Equivalent to the
.Fa f_fsid
field of the
.Vt statfs
structure returned by
.Xr statfs 2 .
.
.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
.Aq Pa sys/vnode.h .
.
.It ATTR_CMN_OBJTAG
An
.Vt fsobj_tag_t
that identifies the type of file system containing the object.
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 a mounted 
volume for the duration of its 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 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 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
.
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 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
Unicode and traditional Mac OS script encodings.
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.
.
.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
.Xr stat 2 .
.
.It ATTR_CMN_CHGTIME
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
.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.
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
structure).
.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),
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
.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
.Xr stat 2 .
.
.It ATTR_CMN_ACCESSMASK
(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 .
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 u_int32_t
containing file flags.
Equivalent to the
.Fa st_flags
field of the
.Vt stat
structure returned by
.Xr stat 2 .
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
.
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 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
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
.
Volume attributes relate to volumes (that is, mounted file systems).
The following volume attributes are defined.
.
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
.It ATTR_VOL_INFO
For historical reasons you must set
.Dv ATTR_VOL_INFO
in the
.Fa volattr
field if you request any other volume attributes.
.
.It ATTR_VOL_FSTYPE
A
.Vt u_int32_t
containing the file system type.
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 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.
.
.It ATTR_VOL_SIZE
An
.Vt off_t
containing the total size of the volume in bytes.
.
.It ATTR_VOL_SPACEFREE
An
.Vt off_t
containing the free space on the volume in bytes.
.
.It ATTR_VOL_SPACEAVAIL
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
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
.Xr statfs 2 .
.
.It ATTR_VOL_MINALLOCATION
An
.Vt off_t
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
.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
this much space each time in order to reduce fragmentation.
.
.It ATTR_VOL_IOBLOCKSIZE
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 u_int32_t
containing the number of file system objects on the volume.
.
.It ATTR_VOL_FILECOUNT
A
.Vt u_int32_t
containing the number of files on the volume.
.
.It ATTR_VOL_DIRCOUNT
A
.Vt u_int32_t
containing the number of directories on the volume.
.
.It ATTR_VOL_MAXOBJCOUNT
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
.Vt attrreference
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
.Dv MAXPATHLEN .
Equivalent to the
.Fa f_mntonname
field of the
.Vt statfs
structure returned by
.Xr statfs 2 .
.
.It ATTR_VOL_NAME
(read/write) An
.Vt attrreference
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
.Dv NAME_MAX +
1.
.Pp
.
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 u_int32_t
containing the volume mount flags.
This is a copy of the value passed to the
.Fa flags
parameter of
.Xr mount 2
when the volume was mounted.
Equivalent to the
.Fa f_flags
field of the
.Vt statfs
structure returned by
.Xr statfs 2 .
.
.It ATTR_VOL_MOUNTEDDEVICE
An
.Vt attrreference
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
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
.Dv MAXPATHLEN .
.Pp
.
.It ATTR_VOL_ENCODINGSUSED
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
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.
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.
This structure is discussed below, along with volume capabilities.
.
.El
.
.Sh DIRECTORY ATTRIBUTES
.
The following directory attributes are defined.
.
.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
.
.It ATTR_DIR_LINKCOUNT
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 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 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.
.
.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 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
.Vt off_t
containing the total number of bytes in all forks of the file (the logical size).
.
.It ATTR_FILE_ALLOCSIZE
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 u_int32_t
containing the optimal block size when reading or writing this file's data.
.
.It ATTR_FILE_CLUMPSIZE
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 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 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 u_int32_t
containing the number of forks in the file.
No built-in file systems on Mac OS X currently support forks other
than the data and resource fork.
.
.It ATTR_FILE_FORKLIST
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
other than the data and resource fork.
Because of this, the structure of this attribute's value is not yet defined.
.
.It ATTR_FILE_DATALENGTH
An
.Vt off_t
containing the length of the data fork in bytes (the logical size).
.
.It ATTR_FILE_DATAALLOCSIZE
An
.Vt off_t
containing a count of the bytes on disk used by the data fork (the physical size).
.
.It ATTR_FILE_DATAEXTENTS
An
.Vt extentrecord
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.
New clients should not use this attribute.
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
a variety of reasons.
.
.It ATTR_FILE_RSRCLENGTH
An
.Vt off_t
containing the length of the resource fork in bytes (the logical size).
.
.It ATTR_FILE_RSRCALLOCSIZE
An
.Vt off_t
containing a count of the bytes on disk used by the resource fork (the physical size).
.
.It ATTR_FILE_RSRCEXTENTS
An
.Vt extentrecord
array for the resource fork.
The array contains eight
.Vt diskextent
structures which represent the first
eight extents of the fork.
.Pp
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,
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 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
.
.It ATTR_CMNEXT_NOFIRMLINKPATH
An
.Vt attrreference
structure containing a path that does not have firmlinks 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
canonical path of a hard-linked item.
.It ATTR_CMNEXT_REALDEVID
A
.Vt dev_t
containing the real 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
.Xr stat 2 .
.
.It ATTR_CMNEXT_REALFSID
An
.Vt fsid_t
structure containing the real 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
.Xr statfs 2 .
.
.It ATTR_CMNEXT_CLONEID
A
.Vt u_int64_t
that uniquely identifies the data stream associated with the file
system object.  Useful for finding which files are pure clones of each
other (as they will have the same clone-id).
.
.It ATTR_CMNEXT_EXT_FLAGS
A
.Vt u_int64_t
that contains additional flags with information about the file.  The
flags are:
.
.Bl -tag -width EF_MAY_SHARE_BLOCKS
.
.It EF_MAY_SHARE_BLOCKS
If this bit is set then the file may share blocks with another file
(i.e. it is a clone of another file).
.
.It EF_NO_XATTRS
If this bit is set then the file has no extended attributes.  Useful
for avoiding a call to listxattr().
.
.It EF_IS_SYNC_ROOT
If this bit is set the directory is a "sync root".  This bit will
never be set for regular files.
.
.It EF_IS_PURGEABLE
If this bit is set the item is a "purgeable" item that can be deleted
by the file system when asked to free space.
.
.It EF_IS_SPARSE
If this bit is set the item has sparse regions.
.
.It EF_IS_SYNTHETIC
If this bit is set the item is a synthetic directory/symlink.
.
.El
.
.It ATTR_CMNEXT_RECURSIVE_GENCOUNT
A
.Vt u_int64_t
that represents the recursive generation count of a directory that has
been marked as maintain-dir-stats in an apfs file system.  This
gencount is updated any time any child is modified (as part of the
contract that a maintain-dir-stats directory manages).  If the
directory is not marked maintain-dir-stats, a zero is returned.
.
.El
.Pp
.
.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
structure (shown below) that indicates which features are supported by the volume.
.
.Bd -literal
typedef u_int32_t vol_capabilities_set_t[4];
.Pp
.
#define VOL_CAPABILITIES_FORMAT     0
#define VOL_CAPABILITIES_INTERFACES 1
#define VOL_CAPABILITIES_RESERVED1  2
#define VOL_CAPABILITIES_RESERVED2  3
.Pp
.
typedef struct vol_capabilities_attr {
    vol_capabilities_set_t capabilities;
    vol_capabilities_set_t valid;
} vol_capabilities_attr_t;
.Ed
.Pp
.
The structure contains two fields,
.Fa capabilities
and
.Fa valid .
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
and so on, below.
.
.It VOL_CAPABILITIES_INTERFACES
This element contains information about which optional functions are
supported by the volume format implementation.
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.
A client program should ignore this element.
.
.It VOL_CAPABILITIES_RESERVED2
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
field is valid.
.Pp
.
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
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
and can look up file system objects by their IDs.
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.
.
.It VOL_CAP_FMT_HARDLINKS
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
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
speedy recovery after an unplanned restart.
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,
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.
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_TOTALSIZE ).
.
.Pp
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.
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.
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,
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
(typically making them all upper or all lower case).
A volume that sets
.Dv VOL_CAP_FMT_CASE_SENSITIVE
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 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
information in memory should set this bit.
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 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.
.It VOL_CAP_FMT_SHARED_SPACE
If this bit is set, the volume format supports having multiple logical filesystems
in a single "partition" which share space.
.It VOL_CAP_FMT_VOL_GROUPS
If this bit is set, the volume format supports having multiple logical filesystems
which may be mounted and unmounted together and may present common filesystem
identifier information.
.It VOL_CAP_FMT_SEALED
If this bit is set, the volume is cryptographically sealed and any modifications
may render the volume unusable.
.
.
.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
structure.
.
.Bl -tag -width VOL_CAP_FMT_PERSISTENTOBJECTIDS
.
.It VOL_CAP_INT_SEARCHFS
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
.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.
.
.It VOL_CAP_INT_READDIRATTR
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
.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
.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
.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
.Dv F_GETLK ,
.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
.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.
.
.It VOL_CAP_INT_RENAME_OPENFAIL
If this bit is set, the file system may fail a rename operation
of a directory if one of its descendents is open.
See
.Xr rename 2
for more details.
.
.El
.Pp
.
.\" vol_attributes_attr_t
.
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
structure (shown below).
.
.Bd -literal
typedef struct attribute_set {
    attrgroup_t commonattr; /* common attribute group */
    attrgroup_t volattr;    /* volume attribute group */
    attrgroup_t dirattr;    /* directory attribute group */
    attrgroup_t fileattr;   /* file attribute group */
    attrgroup_t forkattr;   /* fork attribute group */
} attribute_set_t;
.Pp
.
typedef struct vol_attributes_attr {
    attribute_set_t validattr;
    attribute_set_t nativeattr;
} vol_attributes_attr_t;
.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
.Vt vol_attributes_attr_t ,
but not in the
.Fa nativeattr
field.
.
.Sh RETURN VALUES
Upon successful completion a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.
.Sh COMPATIBILITY
Not all volumes support
.Fn getattrlist .
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
.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.
Your program is expected to be tolerant of this variant behaviour.
.Pp
.
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 the query.
.
.It Bq Er ENOTDIR
A component of the path prefix for
.Fn getattrlist
is not a directory.
.
.It Bq Er ENAMETOOLONG
A component of a path name for
.Fn getattrlist
exceeded
.Dv NAME_MAX
characters, or an entire path name exceeded
.Dv PATH_MAX
characters.
.
.It Bq Er ENOENT
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 for
.Fn getattrlist .
.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname
for
.Fn getattrlist .
.
.It Bq Er EFAULT
.Fa path ,
.Fa attrList
or
.Em attrBuf
points to an invalid address.
.
.It Bq Er ERANGE
.Fa attrBufSize
is too small to hold a u_int32_t.
.
.It Bq Er EINVAL
The
.Fa bitmapcount
field of
.Fa attrList
is not
.Dv ATTR_BIT_MAP_COUNT .
.
.It Bq Er EINVAL
You requested an invalid attribute.
.
.It Bq Er EINVAL
You requested an attribute that is not supported for this file system object.
.
.It Bq Er EINVAL
You requested volume attributes and directory or file attributes.
.
.It Bq Er EINVAL
You requested volume attributes but
.Fa path
does not reference the root of the volume.
.
.It Bq Er EROFS
The volume is read-only but must be modified in order to return this attribute.
.
.It Bq Er EIO
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
.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
invariably matches the order of attribute mask bit values.
For example,
.Dv ATTR_CMN_NAME
(0x00000001) comes before
.Dv ATTR_CMN_DEVID
(0x00000002) because its value is smaller.
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,
assuming that the volume supports the required attributes.
.
.Bd -literal
#include <assert.h>
#include <stdio.h>
#include <string.h>
#include <sys/attr.h>
#include <sys/errno.h>
#include <unistd.h>
#include <sys/vnode.h>
.Pp
.
typedef struct attrlist attrlist_t;
.Pp
.
struct FInfoAttrBuf {
    u_int32_t       length;
    fsobj_type_t    objType;
    char            finderInfo[32];
}  __attribute__((aligned(4), packed));
typedef struct FInfoAttrBuf FInfoAttrBuf;
.Pp
.
static int FInfoDemo(const char *path)
{
    int             err;
    attrlist_t      attrList;
    FInfoAttrBuf    attrBuf;
.Pp
.
    memset(&attrList, 0, sizeof(attrList));
    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:
                printf("file type    = '%.4s'\en", &attrBuf.finderInfo[0]);
                printf("file creator = '%.4s'\en", &attrBuf.finderInfo[4]);
                break;
            case VDIR:
                printf("directory\en");
                break;
            default:
                printf("other object type, %d\en", attrBuf.objType);
                break;
        }
    }
.Pp
.
    return err;
}
.Ed
.Pp
.
The following code is an alternative implementation that uses nested structures
to group the related attributes.
.
.Bd -literal
#include <assert.h>
#include <stdio.h>
#include <stddef.h>
#include <string.h>
#include <sys/attr.h>
#include <sys/errno.h>
#include <unistd.h>
#include <sys/vnode.h>
.Pp
.
typedef struct attrlist attrlist_t;
.Pp
.
struct FInfo2CommonAttrBuf {
    fsobj_type_t    objType;
    char            finderInfo[32];
} __attribute__((aligned(4), packed));
typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
.Pp
.
struct FInfo2AttrBuf {
    u_int32_t           length;
    FInfo2CommonAttrBuf common;
} __attribute__((aligned(4), packed));;
typedef struct FInfo2AttrBuf FInfo2AttrBuf;
.Pp
.
static int FInfo2Demo(const char *path)
{
    int             err;
    attrlist_t      attrList;
    FInfo2AttrBuf   attrBuf;
.Pp
.
    memset(&attrList, 0, sizeof(attrList));
    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.common.objType) {
            case VREG:
                printf(
                    "file type    = '%.4s'\en",
                    &attrBuf.common.finderInfo[0]
                );
                printf(
                    "file creator = '%.4s'\en",
                    &attrBuf.common.finderInfo[4]
                );
                break;
            case VDIR:
                printf("directory\en");
                break;
            default:
                printf(
                    "other object type, %d\en",
                    attrBuf.common.objType
                );
                break;
        }
    }
.Pp
.
    return err;
}
.Ed
.Pp
.
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
#include <assert.h>
#include <stdio.h>
#include <stddef.h>
#include <string.h>
#include <sys/attr.h>
#include <sys/errno.h>
#include <unistd.h>
#include <sys/vnode.h>
.Pp
.
typedef struct attrlist attrlist_t;
.Pp
.
struct VolAttrBuf {
    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
.
static int VolDemo(const char *path)
{
    int             err;
    attrlist_t      attrList;
    VolAttrBuf      attrBuf;
.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
                           | 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:  %u\en", attrBuf.fileCount);
        printf("ATTR_VOL_DIRCOUNT:   %u\en", attrBuf.dirCount);
        printf(
            "ATTR_VOL_MOUNTPOINT: %.*s\en",
            (int) attrBuf.mountPointRef.attr_length,
            ( ((char *) &attrBuf.mountPointRef)
              + attrBuf.mountPointRef.attr_dataoffset )
        );
        printf(
            "ATTR_VOL_NAME:       %.*s\en",
            (int) attrBuf.volNameRef.attr_length,
            ( ((char *) &attrBuf.volNameRef)
              + attrBuf.volNameRef.attr_dataoffset )
        );
    }
.Pp
.
    return err;
}
.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 access 2 ,
.Xr chflags 2 ,
.Xr exchangedata 2 ,
.Xr fcntl 2 ,
.Xr getattrlistbulk 2 ,
.Xr mount 2 ,
.Xr searchfs 2 ,
.Xr setattrlist 2 ,
.Xr stat 2 ,
.Xr statfs 2
.
.Sh HISTORY
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 .