GETATTRLIST(2) System Calls Manual GETATTRLIST(2)
NAME
getattrlist, fgetattrlist, getattrlistat – get file system attributes
SYNOPSIS
#include <sys/attr.h>
#include <unistd.h>
int
getattrlist(const char* path, struct attrlist * attrList, void * attrBuf,
size_t attrBufSize, unsigned long options);
int
fgetattrlist(int fd, struct attrlist * attrList, void * attrBuf,
size_t attrBufSize, unsigned long options);
int
getattrlistat(int fd, const char *path, struct attrlist * attrList,
void * attrBuf, size_t attrBufSize, unsigned long options);
DESCRIPTION
The getattrlist() function returns attributes (that is, metadata) of file
system objects. getattrlist() works on the file system object named by
path, while fgetattrlist() works on the provided file descriptor fd.
The getattrlistat() system call is equivalent to getattrlist() except in
the case where 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 fd instead of the
current working directory. If getattrlistat() is passed the special
value AT_FDCWD in the fd parameter, the current working directory is used
and the behavior is identical to a call to getattrlist().
You can think of getattrlist() as a seriously enhanced version of
stat(2). The functions return attributes about the specified file system
object into the buffer specified by attrBuf and attrBufSize. The
attrList parameter determines what attributes are returned. The options
parameter lets you control specific aspects of the function's behavior.
Not all volumes support all attributes. See the discussion of
ATTR_VOL_ATTRIBUTES for a discussion of how to determine whether a
particular volume supports a particular attribute.
Furthermore, you should only request the attributes that you need. Some
attributes are expensive to calculate on some volume formats. For
example, 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.
The 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.
The attrList parameter is a pointer to an attrlist structure, as defined
by ⟨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.
typedef u_int32_t attrgroup_t;
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
The fields of the attrlist structure are defined as follows.
bitmapcount Number of attribute bit sets in the structure. In
current systems you must set this to ATTR_BIT_MAP_COUNT.
reserved Reserved. You must set this to 0.
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.
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. 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.
dirattr A bit set that specifies the directory attributes that
you require. See below for a description of these
attributes.
fileattr A bit set that specifies the file attributes that you
require. See below for a description of these
attributes.
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.
Unless otherwise noted in the lists below, attributes are read-only.
Attributes labelled as read/write can be set using setattrlist(2).
The attrBuf and 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.
The options parameter is a bit set that controls the behaviour of the
functions. The following option bits are defined.
FSOPT_NOFOLLOW If this bit is set, getattrlist() will not follow
a symlink if it occurs as the last component of
path.
FSOPT_NOFOLLOW_ANY If this bit is set, getattrlist() will not follow
a symlink if it occurs as the last component of
path. In addition an error is returned if a
symlink is encountered before the last component
of path.
FSOPT_REPORT_FULLSIZE The size of the attributes reported (in the first
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.
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 ATTR_CMN_RETURNED_ATTRS be
requested.
FSOPT_ATTR_CMN_EXTENDED
If this is bit is set, then ATTR_CMN_GEN_COUNT
and ATTR_CMN_DOCUMENT_ID can be requested. When
this option is used, forkattrs are reinterpreted
as a set of extended common attributes.
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.
ATTRIBUTE BUFFER
The data returned in the buffer described by attrBuf and attrBufSize is
formatted as follows.
1. The first element of the buffer is a u_int32_t that contains the
overall length, in bytes, of the attributes returned. This size
includes the length field itself.
2. 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).
3. The attributes are placed into the attribute buffer in the order
that they are described below.
4. Each attribute is aligned to a 4-byte boundary (including 64-bit
data types).
If the attribute is of variable length, it is represented in the list by
an attrreference structure, as defined by ⟨sys/attr.h⟩ (shown below).
typedef struct attrreference {
int32_t attr_dataoffset;
u_int32_t attr_length;
} attrreference_t;
This structure contains a 'pointer' to the variable length attribute
data. The attr_length field is the length of the attribute data (in
bytes). The attr_dataoffset field is the offset in bytes from the
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.
The getattrlist() function will silently truncate attribute data if
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 attrBufSize that is large enough
to accommodate the known size of the attributes in the attribute list
(including the leading length field).
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 attrRef is a pointer to the attrreference_t, ( ( (char *) attrRef ) +
attr_dataoffset ) > ( ( (char *) attrBuf ) + attrSize ) ) or, indeed, for
the attribute data to extend beyond the end of the attribute buffer (that
is, ( ( (char *) attrRef ) + attr_dataoffset + attr_datalength ) > ( (
(char *) attrBuf ) + attrSize ) ). If this happens you must increase the
size of the buffer and call getattrlist() to get an accurate copy of the
attribute.
COMMON ATTRIBUTES
Common attributes relate to all types of file system objects. The
following common attributes are defined.
ATTR_CMN_RETURNED_ATTRS An 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 getattrlist(2) and
getatttrlistbulk(2) support this attribute
while searchfs(2) does not.
ATTR_CMN_NAME An 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 NAME_MAX + 1
characters, which is NAME_MAX * 3 + 1 bytes (as
one UTF-8-encoded character may take up to
three bytes).
ATTR_CMN_DEVID A dev_t containing the device number of the
device on which this file system object's
volume is mounted. Equivalent to the st_dev
field of the stat structure returned by
stat(2).
ATTR_CMN_FSID An fsid_t structure containing the file system
identifier for the volume on which the file
system object resides. Equivalent to the
f_fsid field of the statfs structure returned
by statfs(2).
ATTR_CMN_OBJTYPE An fsobj_type_t that identifies the type of
file system object. The values are taken from
enum vtype in ⟨sys/vnode.h⟩.
ATTR_CMN_OBJTAG An fsobj_tag_t that identifies the type of file
system containing the object. The values are
taken from enum vtagtype in ⟨sys/vnode.h⟩.
ATTR_CMN_OBJID An 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.
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), no
relation between the two attributes should ever
be implied.
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 getLinkIDInfo()
function in the EXAMPLES section.
ATTR_CMN_OBJPERMANENTID An 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.
Some file systems can not return this attribute
when the volume is mounted read-only and will
fail the request with error EROFS.
(e.g. original HFS modifies on disk structures
to generate persistent identifiers, and hence
cannot do so if the volume is mounted read
only.)
ATTR_CMN_PAROBJID An 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.
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.
ATTR_CMN_SCRIPT (read/write) A 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.
ATTR_CMN_CRTIME (read/write) A timespec structure containing
the time that the file system object was
created.
ATTR_CMN_MODTIME (read/write) A timespec structure containing
the time that the file system object was last
modified. Equivalent to the st_mtimespec field
of the stat structure returned by stat(2).
ATTR_CMN_CHGTIME A timespec structure containing the time that
the file system object's attributes were last
modified. Equivalent to the st_ctimespec field
of the stat structure returned by stat(2).
ATTR_CMN_ACCTIME (read/write) A timespec structure containing
the time that the file system object was last
accessed. Equivalent to the st_atimespec field
of the stat structure returned by stat(2).
ATTR_CMN_BKUPTIME (read/write) A 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.
ATTR_CMN_FNDRINFO (read/write) 32 bytes of data for use by the
Finder. Equivalent to the concatenation of a
FileInfo structure and an ExtendedFileInfo
structure (or, for directories, a FolderInfo
structure and an ExtendedFolderInfo structure).
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.
ATTR_CMN_OWNERID (read/write) A uid_t containing the owner of
the file system object. Equivalent to the
st_uid field of the stat structure returned by
stat(2).
ATTR_CMN_GRPID (read/write) A gid_t containing the group of
the file system object. Equivalent to the
st_gid field of the stat structure returned by
stat(2).
ATTR_CMN_ACCESSMASK (read/write) A u_int32_t containing the access
permissions of the file system object.
Equivalent to the st_mode field of the stat
structure returned by stat(2). Only the
permission bits of st_mode are valid; other
bits should be ignored, e.g., by masking with
~S_IFMT.
ATTR_CMN_FLAGS (read/write) A u_int32_t containing file flags.
Equivalent to the st_flags field of the stat
structure returned by stat(2). For more
information about these flags, see chflags(2).
ATTR_CMN_GEN_COUNT A 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.
A generation count value of 0 is invalid and
cannot be used to determine data change.
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.
ATTR_CMN_DOCUMENT_ID A 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.
A document id of 0 is invalid.
ATTR_CMN_USERACCESS A 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 R_OK, W_OK, and X_OK,
respectively. See access(2) for more details.
ATTR_CMN_EXTENDED_SECURITY
A variable-length object (thus an attrreference
structure) containing a kauth_filesec
structure, of which only the ACL entry is used.
ATTR_CMN_UUID A guid_t of the owner of the file system
object. Analoguous to ATTR_CMN_OWNERID.
ATTR_CMN_GRPUUID A guid_t of the group to which the file system
object belongs. Analoguous to ATTR_CMN_GRPID.
ATTR_CMN_FILEID A u_int64_t that uniquely identifies the file
system object within its mounted volume.
Equivalent to st_ino field of the stat
structure returned by stat(2).
ATTR_CMN_PARENTID A u_int64_t that identifies the parent
directory of the file system object.
ATTR_CMN_FULLPATH An 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 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.
ATTR_CMN_ADDEDTIME A 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.
ATTR_CMN_DATA_PROTECT_FLAGS
A u_int32_t that contains the file or
directory's data protection class.
VOLUME ATTRIBUTES
Volume attributes relate to volumes (that is, mounted file systems). The
following volume attributes are defined.
ATTR_VOL_INFO For historical reasons you must set
ATTR_VOL_INFO in the volattr field if you
request any other volume attributes.
ATTR_VOL_FSTYPE A u_int32_t containing the file system type.
Equivalent to the f_type field of the statfs
structure returned by statfs(2). Generally not
a useful value.
ATTR_VOL_SIGNATURE A 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.
ATTR_VOL_SIZE An off_t containing the total size of the
volume in bytes.
ATTR_VOL_SPACEFREE An off_t containing the free space on the
volume in bytes.
ATTR_VOL_SPACEAVAIL An 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.
ATTR_VOL_SPACEAVAIL is to ATTR_VOL_SPACEFREE as
f_bavail is to f_bfree in statfs(2).
ATTR_VOL_SPACEUSED An off_t containing the total space used on the
volume in bytes. On space sharing volumes,
this value may not be identical to the
difference between the volume's size and its
free space.
ATTR_VOL_MINALLOCATION An 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.
ATTR_VOL_ALLOCATIONCLUMP An 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.
ATTR_VOL_IOBLOCKSIZE A u_int32_t containing the optimal block size
when reading or writing data. Equivalent to
the f_iosize field of the statfs structure
returned by statfs(2).
ATTR_VOL_OBJCOUNT A u_int32_t containing the number of file
system objects on the volume.
ATTR_VOL_FILECOUNT A u_int32_t containing the number of files on
the volume.
ATTR_VOL_DIRCOUNT A u_int32_t containing the number of
directories on the volume.
ATTR_VOL_MAXOBJCOUNT A u_int32_t containing the maximum number of
file system objects that can be stored on the
volume.
ATTR_VOL_MOUNTPOINT An 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 MAXPATHLEN.
Equivalent to the f_mntonname field of the
statfs structure returned by statfs(2).
ATTR_VOL_NAME (read/write) An 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
NAME_MAX + 1.
This attribute is only read/write if the
VOL_CAP_INT_VOL_RENAME bit is set in the volume
capabilities (see below).
ATTR_VOL_MOUNTFLAGS A u_int32_t containing the volume mount flags.
This is a copy of the value passed to the flags
parameter of mount(2) when the volume was
mounted. Equivalent to the f_flags field of
the statfs structure returned by statfs(2).
ATTR_VOL_MOUNTEDDEVICE An attrreference structure that returns the
same value as the f_mntfromname field of the
statfs structure returned by 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 MAXPATHLEN.
ATTR_VOL_ENCODINGSUSED An unsigned long long containing a bitmap of
the text encodings used on this volume. For
more information about this, see the discussion
of encodingsBitmap in DTS Technote 1150 "HFS
Plus Volume Format".
ATTR_VOL_CAPABILITIES A vol_capabilities_attr_t structure describing
the optional features supported by this volume.
See below for a discussion of volume
capabilities.
ATTR_VOL_UUID A uuid_t containing the file system UUID.
Typically this will be a version 5 UUID.
ATTR_VOL_MOUNTEXTFLAGS A u_int32_t containing the volume extended
mount flags. Equivalent to the f_flags_ext
field of the statfs structure returned by
statfs(2).
ATTR_VOL_QUOTA_SIZE An off_t containing the maximum size of the
volume in bytes.
ATTR_VOL_RESERVED_SIZE An off_t containing the minimum size of the
volume in bytes.
ATTR_VOL_ATTRIBUTES A vol_attributes_attr_t structure describing
the attributes supported by this volume. This
structure is discussed below, along with volume
capabilities.
ATTR_VOL_FSTYPENAME An attrreference structure containing the file
system type name as a UTF-8 encoded, null
terminated C string. The attribute data length
will not be greater than MFSTYPENAMELEN.
ATTR_VOL_FSSUBTYPE A u_int32_t containing the file system sub-
type. Equivalent to the f_fssubtype field of
the statfs structure returned by statfs(2).
DIRECTORY ATTRIBUTES
The following directory attributes are defined.
ATTR_DIR_LINKCOUNT A 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.
ATTR_DIR_ENTRYCOUNT A 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.
ATTR_DIR_MOUNTSTATUS A u_int32_t containing flags describing what's
mounted on the directory. Currently the only
flag defined is DIR_MNTSTATUS_MNTPOINT, which
indicates that there is a file system mounted
on this directory.
ATTR_DIR_ALLOCSIZE An off_t containing the number of bytes on disk
used by the directory (the physical size).
ATTR_DIR_IOBLOCKSIZE A u_int32_t containing the optimal block size
when reading or writing data.
ATTR_DIR_DATALENGTH An off_t containing the length of the directory
in bytes (the logical size).
Requested directory attributes are not returned for file system objects
that are not directories.
FILE ATTRIBUTES
The following file attributes are defined.
ATTR_FILE_LINKCOUNT A u_int32_t containing the number of hard links
to this file. Equivalent to the st_nlink field
of the stat structure returned by stat(2).
ATTR_FILE_TOTALSIZE An off_t containing the total number of bytes
in all forks of the file (the logical size).
ATTR_FILE_ALLOCSIZE An off_t containing a count of the bytes on
disk used by all of the file's forks (the
physical size).
ATTR_FILE_IOBLOCKSIZE A u_int32_t containing the optimal block size
when reading or writing this file's data.
ATTR_FILE_CLUMPSIZE A 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.
ATTR_FILE_DEVTYPE (read/write) A u_int32_t containing the device
type for a special device file. Equivalent to
the st_rdev field of the stat structure
returned by stat(2).
ATTR_FILE_FILETYPE A u_int32_t that whose value is reserved.
Clients should ignore its value. New volume
format implementations should not support this
attribute.
ATTR_FILE_FORKCOUNT A 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.
ATTR_FILE_FORKLIST An 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.
ATTR_FILE_DATALENGTH An off_t containing the length of the data fork
in bytes (the logical size).
ATTR_FILE_DATAALLOCSIZE An off_t containing a count of the bytes on
disk used by the data fork (the physical size).
ATTR_FILE_DATAEXTENTS An extentrecord array for the data fork. The
array contains eight diskextent structures
which represent the first eight extents of the
fork.
This attributes exists for compatibility
reasons. New clients should not use this
attribute. Rather, they should use the
F_LOG2PHYS command in fcntl(2).
In current implementations the value may not be
entirely accurate for a variety of reasons.
ATTR_FILE_RSRCLENGTH An off_t containing the length of the resource
fork in bytes (the logical size).
ATTR_FILE_RSRCALLOCSIZE An off_t containing a count of the bytes on
disk used by the resource fork (the physical
size).
ATTR_FILE_RSRCEXTENTS An extentrecord array for the resource fork.
The array contains eight diskextent structures
which represent the first eight extents of the
fork.
See also ATTR_FILE_DATAEXTENTS.
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.
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.
ATTR_FORK_TOTALSIZE Deprecated. An off_t containing the length of
the fork in bytes (the logical size).
ATTR_FORK_ALLOCSIZE Deprecated. An off_t containing a count of the
bytes on disk used by the fork (the physical
size).
ATTR_FORK_RESERVED Reserved. You must set this to 0.
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.
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.
ATTR_CMNEXT_RELPATH An 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 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.
ATTR_CMNEXT_PRIVATESIZE An off_t containing the number of bytes
that are not trapped inside a clone or
snapshot, and which would be freed
immediately if the file were deleted.
ATTR_CMNEXT_LINKID A u_int64_t that uniquely identifies the
file system object within a mounted
volume for the duration of its mount.
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), no
relation between the two attributes
should ever be implied.
ATTR_CMNEXT_NOFIRMLINKPATH An 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
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.
ATTR_CMNEXT_REALDEVID A dev_t containing the real device number
of the device on which this file system
object's volume is mounted. Equivalent
to the st_dev field of the stat structure
returned by stat(2).
ATTR_CMNEXT_REALFSID An fsid_t structure containing the real
file system identifier for the volume on
which the file system object resides.
Equivalent to the f_fsid field of the
statfs structure returned by statfs(2).
ATTR_CMNEXT_CLONEID A 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).
ATTR_CMNEXT_EXT_FLAGS A u_int64_t that contains additional
flags with information about the file.
The flags are:
EF_MAY_SHARE_BLOCKS If this bit is set
then the file may
share blocks with
another file (i.e.
it may be a clone
of another file).
EF_NO_XATTRS If this bit is set
then the file has
no extended
attributes. Useful
for avoiding a call
to listxattr().
EF_IS_SYNC_ROOT If this bit is set
the directory is a
"sync root". This
bit will never be
set for regular
files.
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.
EF_IS_SPARSE If this bit is set
the item has sparse
regions.
EF_IS_SYNTHETIC If this bit is set
the item is a
synthetic
directory/symlink.
EF_SHARES_ALL_BLOCKS If this bit is set
then the file
shares all of its
blocks with another
file (i.e. it is a
full clone of
another file). For
compatibility
reasons,
EF_SHARES_ALL_BLOCKS
means
EF_MAY_SHARE_BLOCKS
as well.
ATTR_CMNEXT_RECURSIVE_GENCOUNT A 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.
ATTR_CMNEXT_ATTRIBUTION_TAG An optional u_int64_t id that represents
the bundle id (owner) assoicated with the
file (zero means the file isn't
attributed yet)
ATTR_CMNEXT_CLONE_REFCNT A u_int32_t that represents the number of
full clones (each shares all of its
blocks with this file).
VOLUME CAPABILITIES
Not all volumes support all features. The ATTR_VOL_CAPABILITIES
attribute returns a vol_capabilities_attr_t structure (shown below) that
indicates which features are supported by the volume.
typedef u_int32_t vol_capabilities_set_t[4];
#define VOL_CAPABILITIES_FORMAT 0
#define VOL_CAPABILITIES_INTERFACES 1
#define VOL_CAPABILITIES_RESERVED1 2
#define VOL_CAPABILITIES_RESERVED2 3
typedef struct vol_capabilities_attr {
vol_capabilities_set_t capabilities;
vol_capabilities_set_t valid;
} vol_capabilities_attr_t;
The structure contains two fields, capabilities and valid. Each consists
of an array of four elements. The arrays are indexed by the following
values.
VOL_CAPABILITIES_FORMAT This element contains information about
the volume format. See
VOL_CAP_FMT_PERSISTENTOBJECTIDS and so
on, below.
VOL_CAPABILITIES_INTERFACES This element contains information about
which optional functions are supported
by the volume format implementation.
See VOL_CAP_INT_SEARCHFS and so on,
below.
VOL_CAPABILITIES_RESERVED1 Reserved. A file system implementation
should set this element to zero. A
client program should ignore this
element.
VOL_CAPABILITIES_RESERVED2 Reserved. A file system implementation
should set this element to zero. A
client program should ignore this
element.
The 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 capabilities field is valid.
The capabilities field contains bit sets that indicate whether a
particular feature is implemented by this volume format.
The following bits are defined in the first element (indexed by
VOL_CAPABILITIES_FORMAT) of the capabilities and valid fields of the
vol_capabilities_attr_t structure.
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 ATTR_CMN_OBJPERMANENTID
for details about how to obtain these
identifiers.
VOL_CAP_FMT_SYMBOLICLINKS If this bit is set the volume format
supports symbolic links.
VOL_CAP_FMT_HARDLINKS If this bit is set the volume format
supports hard links.
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.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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
VOL_CAP_FMT_JOURNAL is also set.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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,
ATTR_FILE_ALLOCSIZE <
ATTR_FILE_TOTALSIZE ).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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
VOL_CAP_FMT_CASE_SENSITIVE must also set
VOL_CAP_FMT_CASE_PRESERVING.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_FMT_FAST_STATFS This bit is used as a hint to upper
layers to indicate that statfs(2) is
fast enough that its results need not be
cached by the caller. A volume format
implementation that caches the 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 statfs(2)
should not set this bit.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
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.
Introduced with Darwin 8.0 (Mac OS X
version 10.4).
VOL_CAP_FMT_OPENDENYMODES If this bit is set, the volume format
supports open deny modes (e.g., "open
for read write, deny write").
VOL_CAP_FMT_HIDDEN_FILES If this bit is set, the volume format
supports the UF_HIDDEN file flag, and
the 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).
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.
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 f_blocks, f_bavail,
and f_bfree in the struct statfs
returned by statfs(2). Historically,
those values were set to 0xFFFFFFFF for
volumes that did not support them.
Introduced with Darwin 10.0 (Mac OS X
version 10.6).
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.
VOL_CAP_FMT_DOCUMENT_ID If this bit is set, the volume format
supports document IDs (an ID which
persists across object ID changes) for
document revisions.
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.
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.
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.
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.
VOL_CAP_FMT_SEALED If this bit is set, the volume is
cryptographically sealed and any
modifications may render the volume
unusable.
VOL_CAP_FMT_CLONE_MAPPING If this bit is set, the volume format
supports full clone tracking. See
ATTR_CMNEXT_CLONE_REFCNT and
ATTR_CMNEXT_CLONEID for more details.
Other features like extended directory
statistics, for fast directory sizing,
and attribution tags may be supported as
well. See VOL_CAP_INT_ATTRIBUTION_TAG
for more details related to tagging.
The following bits are defined in the second element (indexed by
VOL_CAPABILITIES_INTERFACES) of the capabilities and valid fields of the
vol_capabilities_attr_t structure.
VOL_CAP_INT_SEARCHFS If this bit is set the volume format
implementation supports searchfs(2).
VOL_CAP_INT_ATTRLIST If this bit is set the volume format
implementation supports getattrlist()
and setattrlist(2).
VOL_CAP_INT_NFSEXPORT If this bit is set the volume format
implementation allows this volume to be
exported via NFS.
VOL_CAP_INT_READDIRATTR If this bit is set the volume format
implementation supports
getdirentriesattr(2).
VOL_CAP_INT_EXCHANGEDATA If this bit is set the volume format
implementation supports exchangedata(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_INT_COPYFILE If this bit is set the volume format
implementation supports the (private and
undocumented) copyfile() function.
(This is not the copyfile(3) function.)
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_INT_ALLOCATE If this bit is set the volume format
implementation supports the
F_PREALLOCATE selector of fcntl(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_INT_VOL_RENAME If this bit is set the volume format
implementation allows you to modify the
volume name using setattrlist(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_INT_ADVLOCK If this bit is set the volume format
implementation supports advisory
locking, that is, the F_GETLK, F_SETLK,
and F_SETLKW selectors to fcntl(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_INT_FLOCK If this bit is set the volume format
implementation supports whole file
locks. This includes flock(2) and the
O_EXLOCK and O_SHLOCK flags to open(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOL_CAP_INT_EXTENDED_SECURITY If this bit is set the volume format
implementation supports extended
security controls (ACLs).
Introduced with Darwin 8.0 (Mac OS X
version 10.4).
VOL_CAP_INT_USERACCESS If this bit is set the volume format
implementation supports the
ATTR_CMN_USERACCESS attribute.
Introduced with Darwin 8.0 (Mac OS X
version 10.4).
VOL_CAP_INT_MANLOCK If this bit is set, the volume format
implementation supports AFP-style
mandatory byte range locks via ioctl(2).
VOL_CAP_INT_EXTENDED_ATTR If this bit is set, the volume format
implementation supports native extended
attributes (see setxattr(2)).
VOL_CAP_INT_CLONE If this bit is set, the file system
supports cloning files and directories.
See clonefileat(2) for more details.
VOL_CAP_INT_SNAPSHOT If this bit is set, the file system
supports snapshots. See
fs_snapshot_create(2) for more details.
VOL_CAP_INT_NAMEDSTREAMS If this bit is set, the volume format
implementation supports native named
streams.
VOL_CAP_INT_RENAME_SWAP If this bit is set, the file system
supports swapping file system objects.
See rename(2) for more details.
VOL_CAP_INT_RENAME_EXCL If this bit is set, the file system
supports an exclusive rename operation.
See rename(2) for more details.
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
rename(2) for more details.
VOL_CAP_INT_ATTRIBUTION_TAG If this bit is set, the file system
supports establishing an owner
relationship between a file (excluding
small files) and a process on the first
read/write/truncate/clone operation.
See ATTR_CMNEXT_ATTRIBUTION_TAG for more
details.
VOL_CAP_INT_PUNCHHOLE If this bit is set, the file system
supports the F_PUNCHOLE operation. See
fcntl(2) for more details.
A volume can also report which attributes it supports. This information
is returned by the ATTR_VOL_ATTRIBUTES attribute, which returns a
vol_attributes_attr_t structure (shown below).
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;
typedef struct vol_attributes_attr {
attribute_set_t validattr;
attribute_set_t nativeattr;
} vol_attributes_attr_t;
The validattr field consists of a number of bit sets that indicate
whether an attribute is supported by the volume format implementation.
The 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 ATTR_VOL_ATTRIBUTES attribute would return
ATTR_CMN_OBJPERMANENTID set in the validattr field of the
vol_attributes_attr_t, but not in the nativeattr field.
RETURN VALUES
Upon successful completion a value of 0 is returned. Otherwise, a value
of -1 is returned and errno is set to indicate the error.
COMPATIBILITY
Not all volumes support getattrlist(). The best way to test whether a
volume supports this function is to simply call it and check the error
result. getattrlist() will return ENOTSUP if it is not supported on a
particular volume.
The 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.
If you're implementing a volume format that supports getattrlist(), you
should be careful to support the behaviour specified by this document.
ERRORS
getattrlist() and fgetattrlist() will fail if:
[ENOTSUP] The volume does not support the query.
[ENOTDIR] A component of the path prefix for getattrlist() is
not a directory.
[ENAMETOOLONG] A component of a path name for getattrlist() exceeded
NAME_MAX characters, or an entire path name exceeded
PATH_MAX characters.
[ENOENT] The file system object for getattrlist() does not
exist.
[EBADF] The file descriptor argument for fgetattrlist() is not
a valid file descriptor.
[EACCES] Search permission is denied for a component of the
path prefix for getattrlist().
[ELOOP] Too many symbolic links were encountered in
translating the pathname for getattrlist().
[ELOOP] FSOPT_NOFOLLOW_ANY was passed and a symbolic link was
encountered in translating the pathname for
getattrlist().
[EFAULT] path, attrList or attrBuf points to an invalid
address.
[ERANGE] attrBufSize is too small to hold a u_int32_t.
[EINVAL] The bitmapcount field of attrList is not
ATTR_BIT_MAP_COUNT.
[EINVAL] You requested an invalid attribute.
[EINVAL] You requested an attribute that is not supported for
this file system object.
[EINVAL] You requested volume attributes and directory or file
attributes.
[EINVAL] You requested volume attributes but path does not
reference the root of the volume.
[EROFS] The volume is read-only but must be modified in order
to return this attribute.
[EIO] An I/O error occurred while reading from or writing to
the file system.
In addition to the errors returned by the getattrlist(), the
getattrlistat() function may fail if:
[EBADF] The path argument does not specify an absolute path
and the fd argument is neither AT_FDCWD nor a valid
file descriptor open for searching.
[ENOTDIR] The path argument is not an absolute path and fd is
neither AT_FDCWD nor a file descriptor associated with
a directory.
CAVEATS
If you request any volume attributes, you must set ATTR_VOL_INFO in the
volattr field, even though it generates no result in the attribute
buffer.
The order that attributes are stored in the attribute buffer almost
invariably matches the order of attribute mask bit values. For example,
ATTR_CMN_NAME (0x00000001) comes before ATTR_CMN_DEVID (0x00000002)
because its value is smaller. When ordering attributes, you should
always use the order in which they are described above.
The 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.
If you use a structure for the attribute data, it must be correctly
packed and aligned (see examples).
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.
For more caveats, see also the compatibility notes above.
EXAMPLES
The following code prints the file type and creator of a file, assuming
that the volume supports the required attributes.
#include <assert.h>
#include <stdio.h>
#include <string.h>
#include <sys/attr.h>
#include <sys/errno.h>
#include <unistd.h>
#include <sys/vnode.h>
typedef struct attrlist attrlist_t;
struct FInfoAttrBuf {
u_int32_t length;
fsobj_type_t objType;
char finderInfo[32];
} __attribute__((aligned(4), packed));
typedef struct FInfoAttrBuf FInfoAttrBuf;
static int FInfoDemo(const char *path)
{
int err;
attrlist_t attrList;
FInfoAttrBuf attrBuf;
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
if (err != 0) {
err = errno;
}
if (err == 0) {
assert(attrBuf.length == sizeof(attrBuf));
printf("Finder information for %s:\n", path);
switch (attrBuf.objType) {
case VREG:
printf("file type = '%.4s'\n", &attrBuf.finderInfo[0]);
printf("file creator = '%.4s'\n", &attrBuf.finderInfo[4]);
break;
case VDIR:
printf("directory\n");
break;
default:
printf("other object type, %d\n", attrBuf.objType);
break;
}
}
return err;
}
The following code is an alternative implementation that uses nested
structures to group the related attributes.
#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>
typedef struct attrlist attrlist_t;
struct FInfo2CommonAttrBuf {
fsobj_type_t objType;
char finderInfo[32];
} __attribute__((aligned(4), packed));
typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
struct FInfo2AttrBuf {
u_int32_t length;
FInfo2CommonAttrBuf common;
} __attribute__((aligned(4), packed));;
typedef struct FInfo2AttrBuf FInfo2AttrBuf;
static int FInfo2Demo(const char *path)
{
int err;
attrlist_t attrList;
FInfo2AttrBuf attrBuf;
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
if (err != 0) {
err = errno;
}
if (err == 0) {
assert(attrBuf.length == sizeof(attrBuf));
printf("Finder information for %s:\n", path);
switch (attrBuf.common.objType) {
case VREG:
printf(
"file type = '%.4s'\n",
&attrBuf.common.finderInfo[0]
);
printf(
"file creator = '%.4s'\n",
&attrBuf.common.finderInfo[4]
);
break;
case VDIR:
printf("directory\n");
break;
default:
printf(
"other object type, %d\n",
attrBuf.common.objType
);
break;
}
}
return err;
}
The following example shows how to deal with variable length attributes.
It assumes that the volume specified by path supports the necessary
attributes.
#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>
typedef struct attrlist attrlist_t;
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;
static int VolDemo(const char *path)
{
int err;
attrlist_t attrList;
VolAttrBuf attrBuf;
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;
err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
if (err != 0) {
err = errno;
}
if (err == 0) {
assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace));
assert(attrBuf.length <= sizeof(attrBuf));
printf("Volume information for %s:\n", path);
printf("ATTR_VOL_FILECOUNT: %u\n", attrBuf.fileCount);
printf("ATTR_VOL_DIRCOUNT: %u\n", attrBuf.dirCount);
printf(
"ATTR_VOL_MOUNTPOINT: %.*s\n",
(int) attrBuf.mountPointRef.attr_length,
( ((char *) &attrBuf.mountPointRef)
+ attrBuf.mountPointRef.attr_dataoffset )
);
printf(
"ATTR_VOL_NAME: %.*s\n",
(int) attrBuf.volNameRef.attr_length,
( ((char *) &attrBuf.volNameRef)
+ attrBuf.volNameRef.attr_dataoffset )
);
}
return err;
}
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.
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <err.h>
#include <time.h>
#include <sys/attr.h>
/* 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));
main(int argc, char **argv)
{
int rv;
int i;
for (i = 1; i < argc; i++) {
struct attrlist attrList;
struct AttrListTimes myStat = {0};
char *path = argv[i];
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
attrList.commonattr = ATTR_CMN_CRTIME |
ATTR_CMN_MODTIME;
rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);
if (rv == -1) {
warn("getattrlist(%s)", path);
continue;
}
printf("%s: Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
}
return 0;
}
The getLinkIDInfo() function determines if ATTR_CMNEXT_LINKID and
ATTR_CMN_OBJID
are valid to use on the file system specified by path.
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;
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;
}
SEE ALSO
access(2), chflags(2), exchangedata(2), fcntl(2), getattrlistbulk(2),
mount(2), searchfs(2), setattrlist(2), stat(2), statfs(2)
HISTORY
A getattrlist() function call appeared in Darwin 1.3.1 (Mac OS X version
10.0). The getattrlistat() function call appeared in OS X 10.10 .
Darwin July 31, 2024 Darwin