Manual Pages for UNIX Darwin command on man getattrlist

GETATTRLIST(2) BSD System Calls Manual GETATTRLIST(2)

NAME

ggeettaattttrrlliisstt - get file system attributes

SYNOPSIS

##iinncclluuddee <>

int ggeettaattttrrlliisstt(const char* path, struct attrlist * attrList, void * attrBuf, sizet attrBufSize, unsigned long options);

DESCRIPTION

The ggeettaattttrrlliisstt() function returns attributes (that is, metadata) of file system objects. You can think of ggeettaattttrrlliisstt() 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 behavior. The ggeettaattttrrlliisstt() 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 ggeettaattttrrlliisstt(). Not all volumes support all attributes. See the discussion of

ATTRVOLATTRIBUTES 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, ATTRDIRENTRYCOUNT 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 ATTRBITMAPCOUNT 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 ATTRBITMAPCOUNT. 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 ggeettaattttrrlliisstt(). The following option bits are defined.

FSOPTNOFOLLOW If this bit is set, ggeettaattttrrlliisstt() will not follow a sym-

link if it occurs as the last component of path. AATTTTRRIIBBUUTTEE BBUUFFFFEERR The data returned in the buffer described by attrBuf and attrBufSize is formatted as follows. 1. The first element of the buffer is a uint32t 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 ggeettaattttrrlliisstt() 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 ggeettaattttrrlliisstt() to get an accurate copy of the attribute. CCOOMMMMOONN AATTTTRRIIBBUUTTEESS

Common attributes relate to all types of file system objects. The fol-

lowing common attributes are defined.

ATTRCMNNAME 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.

ATTRCMNDEVID 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). ATTRCMNFSID 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. ATTRCMNOBJTYPE An fsobjtypet that identifies the type of file system object. The values are taken from enum vtype in . ATTRCMNOBJTAG An fsobjtagt that identifies the type of file system containing the object. The values are taken from enum vtagtype in .

ATTRCMNOBJID 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.

ATTRCMNOBJPERMANENTID 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. ATTRCMNPAROBJID 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 ATTRCMNOBJID

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. ATTRCMNSCRIPT (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". ATTRCMNCRTIME (read/write) A timespec structure containing

the time that the file system object was cre-

ated. ATTRCMNMODTIME (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). ATTRCMNCHGTIME (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). ATTRCMNACCTIME (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). ATTRCMNBKUPTIME (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. ATTRCMNFNDRINFO (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. ATTRCMNOWNERID (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). ATTRCMNGRPID (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). ATTRCMNACCESSMASK (read/write) A uint32t containing the access

permissions of the file system object. Equiva-

lent to the stmode field of the stat structure returned by stat(2).

ATTRCMNNAMEDATTRCOUNT A uint32t containing the number of named

attributes of the file system object.

ATTRCMNNAMEDATTRLIST 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. ATTRCMNFLAGS (read/write) A uint32t containing file flags. Equivalent to the stflags field of the stat

structure returned by stat(2). For more infor-

mation 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 ATTRCMNFLAGS. If its order was based on its bit position, it would be before

the ATTRCMNNAMEDATTRCOUNT /

ATTRCMNNAMEDATTRLIST pair, however, it is

placed in the buffer after them.

ATTRCMNUSERACCESS A uint32t containing the effective permis-

sions 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. ATTRCMNFILEID A uint64t that uniquely identifies the file system object within its volume.

ATTRCMNPARENTID A uint64t that identifies the parent direc-

tory of the file system object. VVOOLLUUMMEE AATTTTRRIIBBUUTTEESS Volume attributes relate to volumes (that is, mounted file systems). The following volume attributes are defined. ATTRVOLINFO For reasons that are not at all obvious, you must set ATTRVOLINFO 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. ATTRVOLFSTYPE A uint32t containing the file system type. Equivalent to the ftype field of the statfs structure returned by statfs(2). Generally not a useful value. ATTRVOLSIGNATURE A uint32t 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.

ATTRVOLSIZE An offt containing the total size of the vol-

ume in bytes.

ATTRVOLSPACEFREE An offt containing the free space on the vol-

ume in bytes. ATTRVOLSPACEAVAIL 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. ATTRVOLSPACEAVAIL is to ATTRVOLSPACEFREE as fbavail is to fbfree in statfs(2). ATTRVOLMINALLOCATION 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. ATTRVOLALLOCATIONCLUMP 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. ATTRVOLIOBLOCKSIZE A uint32t containing the optimal block size when reading or writing data. Equivalent to the fiosize field of the statfs structure returned by statfs(2).

ATTRVOLOBJCOUNT A uint32t containing the number of file sys-

tem objects on the volume. ATTRVOLFILECOUNT A uint32t containing the number of files on the volume.

ATTRVOLDIRCOUNT A uint32t containing the number of directo-

ries on the volume. ATTRVOLMAXOBJCOUNT A uint32t containing the maximum number of file system objects that can be stored on the volume. ATTRVOLMOUNTPOINT 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).

ATTRVOLNAME (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). ATTRVOLMOUNTFLAGS A uint32t 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). ATTRVOLMOUNTEDDEVICE 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. ATTRVOLENCODINGSUSED 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". ATTRVOLCAPABILITIES A volcapabilitiesattrt structure describing the optional features supported by this volume.

See below for a discussion of volume capabili-

ties.

ATTRVOLATTRIBUTES A volattributesattrt structure describing

the attributes supported by this volume. This structure is discussed below, along with volume capabilities. DDIIRREECCTTOORRYY AATTTTRRIIBBUUTTEESS The following directory attributes are defined. ATTRDIRLINKCOUNT A uint32t containing the number of hard links to the directory; this does not include the

historical "." and ".." entries. For filesys-

tems that do not support hard links to directo-

ries, this value will be 1.

ATTRDIRENTRYCOUNT A uint32t containing the number of file sys-

tem objects in the directory, not including any synthetic items. ATTRDIRMOUNTSTATUS A uint32t 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. FFIILLEE AATTTTRRIIBBUUTTEESS The following file attributes are defined. ATTRFILELINKCOUNT A uint32t containing the number of hard links to this file. Equivalent to the stnlink field of the stat structure returned by stat(2). ATTRFILETOTALSIZE An offt containing the total number of bytes in all forks of the file (the logical size). ATTRFILEALLOCSIZE An offt containing a count of the bytes on

disk used by all of the file's forks (the phys-

ical size). ATTRFILEIOBLOCKSIZE A uint32t containing the optimal block size when reading or writing this file's data. ATTRFILECLUMPSIZE A uint32t 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. ATTRFILEDEVTYPE (read/write) A uint32t containing the device type for a special device file. Equivalent to the strdev field of the stat structure returned by stat(2). ATTRFILEFILETYPE A uint32t that whose value is reserved. Clients should ignore its value. New volume format implementations should not support this attribute. ATTRFILEFORKCOUNT A uint32t 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. ATTRFILEFORKLIST 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. ATTRFILEDATALENGTH An offt containing the length of the data fork in bytes (the logical size). ATTRFILEDATAALLOCSIZE An offt containing a count of the bytes on disk used by the data fork (the physical size). ATTRFILEDATAEXTENTS 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. ATTRFILERSRCLENGTH An offt containing the length of the resource fork in bytes (the logical size). ATTRFILERSRCALLOCSIZE An offt containing a count of the bytes on disk used by the resource fork (the physical size). ATTRFILERSRCEXTENTS An extentrecord array for the resource fork. The array contains eight diskextent structures which represent the first eight extents of the fork. See also ATTRFILEDATAEXTENTS. FFOORRKK AATTTTRRIIBBUUTTEESS 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. ATTRFORKTOTALSIZE An offt containing the length of the fork in bytes (the logical size). ATTRFORKALLOCSIZE 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. VVOOLLUUMMEE CCAAPPAABBIILLIITTIIEESS Not all volumes support all features. The ATTRVOLCAPABILITIES 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 ATTRCMNOBJPERMANENTID 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). VOLCAPFMTNOROOTTIMES 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, ATTRFILEALLOCSIZE < ATTRFILETOTALSIZE ). 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). VOLCAPINTATTRLIST If this bit is set the volume format implementation supports ggeettaattttrrlliisstt() and setattrlist(2). VOLCAPINTNFSEXPORT If this bit is set the volume format implementation allows this volume to be exported via NFS. VOLCAPINTREADDIRATTR 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). VOLCAPINTALLOCATE If this bit is set the volume format implementation supports the FPREALLOCATE 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). VOLCAPINTEXTENDEDSECURITY If this bit is set the volume format

implementation supports extended secu-

rity controls (ACLs). Introduced with Darwin 8.0 (Mac OS X version 10.4). VOLCAPINTUSERACCESS If this bit is set the volume format implementation supports the ATTRCMNUSERACCESS attribute. Introduced with Darwin 8.0 (Mac OS X version 10.4). A volume can also report which attributes it supports. This information

is returned by the ATTRVOLATTRIBUTES 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 ATTRVOLATTRIBUTES attribute would return

ATTRCMNOBJPERMANENTID 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.

CCOOMMPPAATTIIBBIILLIITTYY Not all volumes support ggeettaattttrrlliisstt(). The best way to test whether a volume supports this function is to simply call it and check the error result. ggeettaattttrrlliisstt() will return ENOTSUP if it is not supported on a particular volume. The ggeettaattttrrlliisstt() 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 ggeettaattttrrlliisstt(), you should be careful to support the behaviour specified by this document. EERRRROORRSS ggeettaattttrrlliisstt() will fail if: [ENOTSUP] The volume does not support ggeettaattttrrlliisstt(). [ENOTDIR] A component of the path prefix is not a directory.

[ENAMETOOLONG] 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. [EACCES] Search permission is denied for a component of the path prefix.

[ELOOP] 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 ATTRBITMAPCOUNT. [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. CCAAVVEEAATTSS If you request any volume attributes, you must set ATTRVOLINFO 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,

ATTRCMNNAME (0x00000001) comes before ATTRCMNDEVID (0x00000002)

because its value is smaller. However, you can not rely on this ordering because there is one key exception: ATTRCMNFLAGS is placed after the

ATTRCMNNAMEDATTRCOUNT / ATTRCMNNAMEDATTRLIST 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. EEXXAAMMPPLLEESS The following code prints the file type and creator of a file, assuming that the volume supports the required attributes.

#include

typedef struct attrlist attrlistt; struct FInfoAttrBuf { uint32t 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 = ATTRBITMAPCOUNT; attrList.commonattr = ATTRCMNOBJTYPE | ATTRCMNFNDRINFO;

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

typedef struct attrlist attrlistt; struct FInfo2CommonAttrBuf { fsobjtypet objType; char finderInfo[32]; }; typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf; struct FInfo2AttrBuf { uint32t 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 = ATTRBITMAPCOUNT; attrList.commonattr = ATTRCMNOBJTYPE | ATTRCMNFNDRINFO;

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

typedef struct attrlist attrlistt; struct VolAttrBuf { uint32t length; uint32t fileCount; uint32t 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 = ATTRBITMAPCOUNT; attrList.volattr = ATTRVOLINFO | ATTRVOLFILECOUNT | ATTRVOLDIRCOUNT | ATTRVOLMOUNTPOINT

| ATTRVOLNAME;

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("ATTRVOLFILECOUNT: %lu\n", attrBuf.fileCount);

printf("ATTRVOLDIRCOUNT: %lu\n", attrBuf.dirCount);

printf(

"ATTRVOLMOUNTPOINT: %.*s\n",

(int) attrBuf.mountPointRef.attrlength, ( ((char *) &attrBuf.mountPointRef) + attrBuf.mountPointRef.attrdataoffset ) ); printf(

"ATTRVOLNAME: %.*s\n",

(int) attrBuf.volNameRef.attrlength, ( ((char *) &attrBuf.volNameRef) + attrBuf.volNameRef.attrdataoffset ) ); } return err; }