GETATRLIST(2) BSD System Calls Manual GETATRLIST(2)
NAME
getattrlist -- get file system attributes
SYNOPSIS
##include <>
##include <>
int
getattrlist(const char* path, struct attrlist * attrList, void * attrBuf,
sizet attrBufSize, unsigned long options);
DESCRIPTION
The getattrlist() function returns attributes (that is, metadata) of file
system objects. You can think of getattrlist() as a seriously enhanced
version of stat(2). The function returns attributes about the file sys-
tem object specified by path in 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 behaviour.
The getattrlist() function is only supported by certain volume format
implementations. For maximum compatibility, client programs should use
high-level APIs (such as the Carbon File Manager) to access file system
attributes. These high-level APIs include logic to emulate file system
attributes on volumes that don't support getattrlist().
Not all volumes support all attributes. See the discussion of
ATRVOLATRIBUTES for a discussion of how to determine whether a par-
ticular 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 exam-
ple, ATRDIRENTRYCOUNT 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 search-
able.
The attrList parameter is a pointer to an attrlist structure, as defined
by (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 uint32t attrgroupt;
struct attrlist {
ushort bitmapcount; /* number of attr. bit sets in list */
uint16t reserved; /* (to maintain 4-byte alignment) */
attrgroupt commonattr; /* common attribute group */
attrgroupt volattr; /* volume attribute group */
attrgroupt dirattr; /* directory attribute group */
attrgroupt fileattr; /* file attribute group */
attrgroupt forkattr; /* fork attribute group */
};
#define ATRBITMAPCOUNT 5
The fields of the attrlist structure are defined as follows.
bitmapcount Number of attribute bit sets in the structure. In cur-
rent systems you must set this to ATRBITMAPCOUNT.
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. If you request volume attributes, path
must reference the root of a volume. In addition, you
can't request volume attributes if you also request file
or directory attributes.
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.
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 suffi-
ciently 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
getattrlist(). The following option bits are defined.
FSOPTNOFOLOW If this bit is set, getattrlist() will not follow a sym-
link if it occurs as the last component of path.
ATRIBUTE BUFER
The data returned in the buffer described by attrBuf and attrBufSize is
formatted as follows.
1. The first element of the buffer is a unsigned long 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.
If the attribute is of variable length, it is represented in the list by
an attrreference structure, as defined by (shown below).
typedef struct attrreference {
long attrdataoffset;
sizet attrlength;
} attrreferencet;
This structure contains a 'pointer' to the variable length attribute
data. The attrlength field is the length of the attribute data (in
bytes). The attrdataoffset field is the offset in bytes from the
attrreference structure to the attribute data. This offset will always
be a multiple of sizeof(unsigned long) bytes, so you can safely access
common data types without fear of alignment 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 attrreferencet, ( ( (char *) attrRef ) ]
attrdataoffset ) > ( ( (char *) attrBuf ) ] attrSize ) ) or, indeed, for
the attribute data to extend beyond the end of the attribute buffer (that
is, ( ( (char *) attrRef ) ] attrdataoffset ] attrdatalength ) > ( (
(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.
COMON ATRIBUTES
Common attributes relate to all types of file system objects. The fol-
lowing common attributes are defined.
ATRCMNAME 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 NAMEMAX ] 1.
ATRCMNDEVID A devt containing the device number of the
device on which this file system object's vol-
ume is mounted. Equivalent to the stdev field
of the stat structure returned by stat(2).
ATRCMNFSID An fsidt structure containing the file system
identifier for the volume on which the file
system object resides. Equivalent to the
ffsid field of the statfs structure returned
by statfs(2).
This value is not related to the file system ID
from traditional Mac OS (for example, the
filesystemID field of the FSVolumeInfo struc-
ture returned by Carbon's FSGetVolumeInfo()
function). On current versions of Mac OS X
that value is synthesised by the Carbon File
Manager.
ATRCMNOBJTYPE An fsobjtypet that identifies the type of
file system object. The values are taken from
enum vtype in .
ATRCMNOBJTAG An fsobjtagt that identifies the type of file
system containing the object. The values are
taken from enum vtagtype in .
ATRCMNOBJID An fsobjidt structure that uniquely identi-
fies the file system object within its volume.
The fidgeneration field of this structure will
be zero for all non-root callers (effective UID
not 0). This identifier need not be persistent
across an unmount/mount sequence.
Some volume formats use well known values for
the fidobjno field for the root directory (2)
and the parent of root directory (1). This is
not a required behaviour of this attribute.
ATRCMNOBJPERMANENTID An fsobjidt structure that uniquely identi-
fies the file system object within its volume.
The fidgeneration field of this structure will
be zero for all non-root callers (effective UID
not 0). This identifier should be persistent
across an unmount/mount sequence.
Some file systems (for example, original HFS)
may need to modify the on-disk structure to
return a persistent identifier. If such a file
system is mounted read-only, an attempt to get
this attribute will fail with the error EROFS.
ATRCMNPAROBJID An fsobjidt structure that identifies the
parent directory of the file system object.
The fidgeneration field of this structure will
be zero for all non-root callers (effective UID
not 0). Equivalent to the ATRCMNOBJID
attribute of the parent directory. This iden-
tifier need not be persistent across an
unmount/mount sequence.
On a volume that supports hard links, a multi-
ply linked file has no unique parent. This
attribute will return an unspecified parent.
For some volume formats this attribute is very
expensive to calculate.
ATRCMNSCRIPT (read/write) A textencodingt containing a
text encoding hint for the file system object's
name. It is included to facilitate the loss-
less round trip conversion of names between
Unicode and traditional Mac OS script encod-
ings. The values are defined in
. File systems that
do not have an appropriate text encoding value
should return kTextEncodingMacUnicode. See DTS
Q&A 1173 "File Manager Text Encoding Hints".
ATRCMNCRTIME (read/write) A timespec structure containing
the time that the file system object was cre-
ated.
ATRCMNMODTIME (read/write) A timespec structure containing
the time that the file system object was last
modified. Equivalent to the stmtimespec field
of the stat structure returned by stat(2).
ATRCMNCHGTIME (read/write) A timespec structure containing
the time that the file system object's
attributes were last modified. Equivalent to
the stctimespec field of the stat structure
returned by stat(2).
ATRCMNACTIME (read/write) A timespec structure containing
the time that the file system object was last
accessed. Equivalent to the statimespec field
of the stat structure returned by stat(2).
ATRCMNBKUPTIME (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.
ATRCMNFNDRINFO (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).
These structures are defined in
.
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.
ATRCMNOWNERID (read/write) A uidt containing the owner of
the file system object. Equivalent to the
stuid field of the stat structure returned by
stat(2).
ATRCMNGRPID (read/write) A gidt containing the group of
the file system object. Equivalent to the
stgid field of the stat structure returned by
stat(2).
ATRCMNACESMASK (read/write) A modet containing the access
permissions of the file system object. Equiva-
lent to the stmode field of the stat structure
returned by stat(2).
ATRCMNAMEDATRCOUNT A unsigned long containing the number of named
attributes of the file system object. No
built-in file systems on Mac OS X currently
support named attributes.
ATRCMNAMEDATRLIST An attrreference structure containing a list of
named attributes of the file system object. No
built-in file systems on Mac OS X currently
support named attributes. Because of this, the
structure of this attribute's value is not yet
defined.
ATRCMNFLAGS (read/write) A unsigned long containing file
flags. Equivalent to the stflags field of the
stat structure returned by stat(2). For more
information about these flags, see chflags(2).
The order that attributes are placed into the
attribute buffer almost invariably matches the
order of the attribute mask bit values. The
exception is ATRCMNFLAGS. If its order was
based on its bit position, it would be before
the ATRCMNAMEDATRCOUNT /
ATRCMNAMEDATRLIST pair, however, it is
placed in the buffer after them.
ATRCMNUSERACES A unsigned long containing the effective per-
missions of the current user (the calling
process's effective UID) for this file system
object. You can test for read, write, and exe-
cute permission using ROK, WOK, and XOK,
respectively. See access(2) for more details.
VOLUME ATRIBUTES
Volume attributes relate to volumes (that is, mounted file systems). The
following volume attributes are defined.
ATRVOLINFO For reasons that are not at all obvious, you
must set ATRVOLINFO in the volattr field if
you request any other volume attributes. This
does not result in any attribute data being
added to the attribute buffer.
ATRVOLFSTYPE A unsigned long containing the file system
type. Equivalent to the ftype field of the
statfs structure returned by statfs(2). Gener-
ally not a useful value.
ATRVOLSIGNATURE A unsigned long containing the volume signature
word. This value is unique within a given file
system type and lets you distinguish between
different volume formats handled by the same
file system. See for more
details.
ATRVOLSIZE An offt containing the total size of the vol-
ume in bytes.
ATRVOLSPACEFRE An offt containing the free space on the vol-
ume in bytes.
ATRVOLSPACEAVAIL An offt 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 criti-
cal disk exhaustion errors. Non-privileged
programs, like a disk management tool, should
use this value to display the space available
to the user.
ATRVOLSPACEAVAIL is to ATRVOLSPACEFRE as
fbavail is to fbfree in statfs(2).
ATRVOLMINALOCATION An offt containing the minimum allocation size
on the volume in bytes. If you create a file
containing one byte, it will consume this much
space.
ATRVOLALOCATIONCLUMP An offt containing the allocation clump size
on the volume, in bytes. As a file is
extended, the file system will attempt to allo-
cate this much space each time in order to
reduce fragmentation.
ATRVOLIOBLOCKSIZE A unsigned long containing the optimal block
size when reading or writing data. Equivalent
to the fiosize field of the statfs structure
returned by statfs(2).
ATRVOLOBJCOUNT A unsigned long containing the number of file
system objects on the volume.
ATRVOLFILECOUNT A unsigned long containing the number of files
on the volume.
ATRVOLDIRCOUNT A unsigned long containing the number of direc-
tories on the volume.
ATRVOLMAXOBJCOUNT A unsigned long containing the maximum number
of file system objects that can be stored on
the volume.
ATRVOLMOUNTPOINT 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 fmntonname field of the
statfs structure returned by statfs(2).
ATRVOLNAME (read/write) An attrreference structure con-
taining the name of the volume as a UTF-8
encoded, null terminated C string. The
attribute data length will not be greater than
NAMEMAX ] 1.
This attribute is only read/write if the
VOLCAPINTVOLRENAME bit is set in the volume
capabilities (see below).
ATRVOLMOUNTFLAGS A unsigned long 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 fflags field
of the statfs structure returned by statfs(2).
ATRVOLMOUNTEDEVICE An attrreference structure that returns the
same value as the fmntfromname 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.
ATRVOLENCODINGSUSED 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".
ATRVOLCAPABILITIES A volcapabilitiesattrt structure describing
the optional features supported by this volume.
See below for a discussion of volume capabili-
ties.
ATRVOLATRIBUTES A volattributesattrt structure describing
the attributes supported by this volume. This
structure is discussed below, along with volume
capabilities.
DIRECTORY ATRIBUTES
The following directory attributes are defined.
ATRDIRLINKCOUNT A unsigned long containing the number of file
system objects in the directory, including syn-
thetic items such as "." and "..". For histor-
ical reasons, you should not always rely on
this value being accurate.
If you're implementing a volume format on which
this is hard to calculate, you should not sup-
port this attribute. While it's traditional to
return a constant value of 1 in the stnlink
field of the stat structure as returned by
stat(2), it's not necessary to do this here
because there is a defined way to indicate that
you do not support the attribute.
ATRDIRENTRYCOUNT A unsigned long containing the number of file
system objects in the directory, not including
any synthetic items.
ATRDIRMOUNTSTATUS A unsigned long containing flags describing
what's mounted on the directory. Currently the
only flag defined is DIRMNTSTATUSMNTPOINT,
which indicates that there is a file system
mounted on this directory. Due to a bug (r.
3502822), this flag is never set on current
system.
FILE ATRIBUTES
The following file attributes are defined.
ATRFILELINKCOUNT A unsigned long containing the number of hard
links to this file. Equivalent to the stnlink
field of the stat structure returned by
stat(2).
ATRFILETOTALSIZE An offt containing the total number of bytes
in all forks of the file (the logical size).
ATRFILEALOCSIZE An offt containing a count of the bytes on
disk used by all of the file's forks (the phys-
ical size).
ATRFILEIOBLOCKSIZE A unsigned long containing the optimal block
size when reading or writing this file's data.
ATRFILECLUMPSIZE A unsigned long containing the allocation clump
size for this file, in bytes. As the file is
extended, the file system will attempt to allo-
cate this much space each time in order to
reduce fragmentation. This value applies to
the data fork.
ATRFILEDEVTYPE (read/write) A unsigned long containing the
device type for a special device file. Equiva-
lent to the strdev field of the stat structure
returned by stat(2).
ATRFILEFILETYPE A unsigned long that whose value is reserved.
Clients should ignore its value. New volume
format implementations should not support this
attribute.
ATRFILEFORKCOUNT A unsigned long 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.
ATRFILEFORKLIST An attrreference structure containing a list of
named forks of the file. No built-in file sys-
tems 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.
ATRFILEDATALENGTH An offt containing the length of the data fork
in bytes (the logical size).
ATRFILEDATALOCSIZE An offt containing a count of the bytes on
disk used by the data fork (the physical size).
ATRFILEDATAEXTENTS 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 rea-
sons. New clients should not use this
attribute. Rather, they should use the
FLOG2PHYS command in fcntl(2).
In current implementations the value may not be
entirely accurate for a variety of reasons.
ATRFILERSRCLENGTH An offt containing the length of the resource
fork in bytes (the logical size).
ATRFILERSRCALOCSIZE An offt containing a count of the bytes on
disk used by the resource fork (the physical
size).
ATRFILERSRCEXTENTS An extentrecord array for the resource fork.
The array contains eight diskextent structures
which represent the first eight extents of the
fork.
See also ATRFILEDATAEXTENTS.
FORK ATRIBUTES
Fork attributes relate to the actual data in the file, which can be held
in multiple named contiguous ranges, or forks. The following fork
attributes are defined.
ATRFORKTOTALSIZE An offt containing the length of the fork in
bytes (the logical size).
ATRFORKALOCSIZE An offt containing a count of the bytes on
disk used by the fork (the physical size).
Fork attributes are not properly implemented by any current Mac OS X vol-
ume 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.
VOLUME CAPABILITIES
Not all volumes support all features. The ATRVOLCAPABILITIES
attribute returns a volcapabilitiesattrt structure (shown below) that
indicates which features are supported by the volume.
typedef uint32t volcapabilitiessett[4];
#define VOLCAPABILITIESFORMAT 0
#define VOLCAPABILITIESINTERFACES 1
#define VOLCAPABILITIESRESERVED1 2
#define VOLCAPABILITIESRESERVED2 3
typedef struct volcapabilitiesattr {
volcapabilitiessett capabilities;
volcapabilitiessett valid;
} volcapabilitiesattrt;
The structure contains two fields, capabilities and valid. Each consists
of an array of four elements. The arrays are indexed by the following
values.
VOLCAPABILITIESFORMAT This element contains information about
the volume format. See
VOLCAPFMTPERSISTENTOBJECTIDS and so
on, below.
VOLCAPABILITIESINTERFACES This element contains information about
which optional functions are supported
by the volume format implementation.
See VOLCAPINTSEARCHFS and so on,
below.
VOLCAPABILITIESRESERVED1 Reserved. A file system implementation
should set this element to zero. A
client program should ignore this ele-
ment.
VOLCAPABILITIESRESERVED2 Reserved. A file system implementation
should set this element to zero. A
client program should ignore this ele-
ment.
The valid field contains bit sets that indicate which flags are known to
the volume format implementation. Each bit indicates whether the con-
tents of the corresponding bit in the capabilities field is valid.
The capabilities field contains bit sets that indicate whether a particu-
lar feature is implemented by this volume format.
The following bits are defined in the first element (indexed by
VOLCAPABILITIESFORMAT) of the capabilities and valid fields of the
volcapabilitiesattrt structure.
VOLCAPFMTPERSISTENTOBJECTIDS If this bit is set the volume format
supports persistent object identifiers
and can look up file system objects by
their IDs. See ATRCMNOBJPERMANENTID
for details about how to obtain these
identifiers.
VOLCAPFMTSYMBOLICLINKS If this bit is set the volume format
supports symbolic links.
VOLCAPFMTHARDLINKS If this bit is set the volume format
supports hard links.
VOLCAPFMTJOURNAL If this bit is set the volume format
supports a journal used to speed recov-
ery 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).
VOLCAPFMTJOURNALACTIVE If this bit is set the volume is cur-
rently using a journal for speedy recov-
ery after an unplanned restart. This
bit can be set only if
VOLCAPFMTJOURNAL is also set.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPFMTNOROTIMES 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 vol-
umes across unmount/mount, and so on.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPFMTSPARSEFILES 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,
ATRFILEALOCSIZE <
ATRFILETOTALSIZE ).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPFMTZERORUNS 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 simi-
lar to sparse files, but not the space
savings.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPFMTCASESENSITIVE If this bit is set the volume format
treats upper and lower case characters
in file and directory names as differ-
ent. 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).
VOLCAPFMTCASEPRESERVING 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
VOLCAPFMTCASESENSITIVE must also set
VOLCAPFMTCASEPRESERVING.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPFMTFASTSTATFS This bit is used as a hint to upper lay-
ers (specifically the Carbon File Man-
ager) 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 net-
work transaction to satisfy statfs(2)
should not set this bit.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPFMT2TBFILESIZE If this bit is set the volume format
supports file sizes upto 2TB. This bit
does not necessarily mean that the file
system does not support file size more
than 2TB. This bit does not mean that
the currently available space on the
volume is 2TB.
Introduced with Darwin 8.0 (Mac OS X
version 10.4).
The following bits are defined in the second element (indexed by
VOLCAPABILITIESINTERFACES) of the capabilities and valid fields of the
volcapabilitiesattrt structure.
VOLCAPINTSEARCHFS If this bit is set the volume format
implementation supports searchfs(2).
VOLCAPINTATRLIST If this bit is set the volume format
implementation supports getattrlist()
and setattrlist(2).
VOLCAPINTNFSEXPORT If this bit is set the volume format
implementation allows this volume to be
exported via NFS.
VOLCAPINTREADIRATR If this bit is set the volume format
implementation supports
getdirentriesattr(2).
VOLCAPINTEXCHANGEDATA If this bit is set the volume format
implementation supports exchangedata(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPINTCOPYFILE If this bit is set the volume format
implementation supports the (private and
undocumented) copyfile() function.
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPINTALOCATE If this bit is set the volume format
implementation supports the
FPREALOCATE selector of fcntl(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPINTVOLRENAME 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).
VOLCAPINTADVLOCK If this bit is set the volume format
implementation supports advisory lock-
ing, that is, the FGETLK, FSETLK, and
FSETLKW selectors to fcntl(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
VOLCAPINTFLOCK If this bit is set the volume format
implementation supports whole file
locks. This includes flock(2) and the
OEXLOCK and OSHLOCK flags to open(2).
Introduced with Darwin 7.0 (Mac OS X
version 10.3).
A volume can also report which attributes it supports. This information
is returned by the ATRVOLATRIBUTES attribute, which returns a
volattributesattrt structure (shown below).
typedef struct attributeset {
attrgroupt commonattr; /* common attribute group */
attrgroupt volattr; /* volume attribute group */
attrgroupt dirattr; /* directory attribute group */
attrgroupt fileattr; /* file attribute group */
attrgroupt forkattr; /* fork attribute group */
} attributesett;
typedef struct volattributesattr {
attributesett validattr;
attributesett nativeattr;
} volattributesattrt;
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 vol-
ume format might support persistent object identifiers, but doing so
requires a complex table lookup that is not part of the core volume for-
mat. In that case, the ATRVOLATRIBUTES attribute would return
ATRCMNOBJPERMANENTID set in the validattr field of the
volattributesattrt, 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 be-
haviour than what is described here. Your program is expected to be tol-
erant 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.
ERORS
getattrlist() will fail if:
[ENOTSUP] The volume does not support getattrlist().
[ENOTDIR] A component of the path prefix is not a directory.
[ENAMETOLONG] A component of a path name exceeded NAMEMAX charac-
ters, or an entire path name exceeded PATHMAX charac-
ters.
[ENOENT] The file system object does not exist.
[EACES] Search permission is denied for a component of the
path prefix.
[ELOP] Too many symbolic links were encountered in translat-
ing the pathname.
[EFAULT] path, attrList or attrBuf points to an invalid
address.
[EINVAL] The bitmapcount field of attrList is not
ATRBITMAPCOUNT.
[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 ref-
erence 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.
CAVEATS
If you request any volume attributes, you must set ATRVOLINFO 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,
ATRCMNAME (0x00000001) comes before ATRCMNDEVID (0x00000002)
because its value is smaller. However, you can not rely on this ordering
because there is one key exception: ATRCMNFLAGS is placed after the
ATRCMNAMEDATRCOUNT / ATRCMNAMEDATRLIST pair, even though its
bit position indicates that it should come before. This is due to a bug
in an early version of Mac OS X that can't be fixed for binary compati-
bility reasons. When ordering attributes, you should always use the
order in which they are described above.
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
#include
#include
#include
#include
#include
#include
typedef struct attrlist attrlistt;
struct FInfoAttrBuf {
unsigned long length;
fsobjtypet objType;
char finderInfo[32];
};
typedef struct FInfoAttrBuf FInfoAttrBuf;
static int FInfoDemo(const char *path)
{
int err;
attrlistt attrList;
FInfoAttrBuf attrBuf;
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATRBITMAPCOUNT;
attrList.commonattr = ATRCMNOBJTYPE ATRCMNFNDRINFO;
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
#include
#include
#include
#include
#include
#include
#include
typedef struct attrlist attrlistt;
struct FInfo2CommonAttrBuf {
fsobjtypet objType;
char finderInfo[32];
};
typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
struct FInfo2AttrBuf {
unsigned long length;
FInfo2CommonAttrBuf common;
};
typedef struct FInfo2AttrBuf FInfo2AttrBuf;
static int FInfo2Demo(const char *path)
{
int err;
attrlistt attrList;
FInfo2AttrBuf attrBuf;
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATRBITMAPCOUNT;
attrList.commonattr = ATRCMNOBJTYPE ATRCMNFNDRINFO;
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
#include
#include
#include
#include
#include
#include
#include
typedef struct attrlist attrlistt;
struct VolAttrBuf {
unsigned long length;
unsigned long fileCount;
unsigned long dirCount;
attrreferencet mountPointRef;
attrreferencet volNameRef;
char mountPointSpace[MAXPATHLEN];
char volNameSpace[MAXPATHLEN];
};
typedef struct VolAttrBuf VolAttrBuf;
static int VolDemo(const char *path)
{
int err;
attrlistt attrList;
VolAttrBuf attrBuf;
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATRBITMAPCOUNT;
attrList.volattr = ATRVOLINFO
ATRVOLFILECOUNT
ATRVOLDIRCOUNT
ATRVOLMOUNTPOINT
ATRVOLNAME;
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("ATRVOLFILECOUNT: %lu\n", attrBuf.fileCount);
printf("ATRVOLDIRCOUNT: %lu\n", attrBuf.dirCount);
printf(
"ATRVOLMOUNTPOINT: %.*s\n",
(int) attrBuf.mountPointRef.attrlength,
( ((char *) &attrBuf.mountPointRef)
] attrBuf.mountPointRef.attrdataoffset )
);
printf(
"ATRVOLNAME: %.*s\n",
(int) attrBuf.volNameRef.attrlength,
( ((char *) &attrBuf.volNameRef)
] attrBuf.volNameRef.attrdataoffset )
);
}
return err;
}
SEE ALSO
access(2), chflags(2), exchangedata(2), fcntl(2), getdirentriesattr(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).
Darwin October 14, 2004 Darwin
|
