2329 lines
62 KiB
Groff
2329 lines
62 KiB
Groff
.\" 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 July 28, 2022
|
|
.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.
|
|
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_NOFOLLOW_ANY
|
|
If this bit is set,
|
|
.Fn getattrlist
|
|
will not follow a symlink if it occurs as
|
|
the last component of
|
|
.Fa path .
|
|
In addition an error is returned if a symlink
|
|
is encountered before 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_SPACEUSED
|
|
An
|
|
.Vt 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.
|
|
.
|
|
.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.
|
|
.
|
|
.It ATTR_VOL_FSTYPENAME
|
|
An
|
|
.Vt 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
|
|
.Dv MFSTYPENAMELEN .
|
|
.
|
|
.It ATTR_VOL_FSSUBTYPE
|
|
A
|
|
.Vt u_int32_t
|
|
containing the file system sub-type.
|
|
Equivalent to the
|
|
.Fa f_fssubtype
|
|
field of the
|
|
.Vt statfs
|
|
structure returned by
|
|
.Xr statfs 2 .
|
|
.
|
|
.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_CMNEXT_RECURSIVE_GENCOUNT
|
|
.
|
|
.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_SHARES_ALL_BLOCKS
|
|
.
|
|
.It 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).
|
|
.
|
|
.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.
|
|
.
|
|
.It 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.
|
|
.
|
|
.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.
|
|
.
|
|
.It ATTR_CMNEXT_ATTRIBUTION_TAG
|
|
An optional
|
|
.Vt u_int64_t
|
|
id that represents the bundle id (owner) assoicated with the file
|
|
(zero means the file isn't attributed yet)
|
|
.
|
|
.It ATTR_CMNEXT_CLONE_REFCNT
|
|
A
|
|
.Vt u_int32_t
|
|
that represents the number of full clones
|
|
(each shares all of its blocks with this file).
|
|
.
|
|
.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_DOCUMENT_ID
|
|
If this bit is set, the volume format supports document IDs
|
|
(an ID which persists across object ID changes) for document revisions.
|
|
.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.
|
|
.It 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.
|
|
.
|
|
.
|
|
.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.
|
|
.
|
|
.It 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.
|
|
.
|
|
.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 ELOOP
|
|
FSOPT_NOFOLLOW_ANY was passed and a symbolic link was 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 .
|