ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages
|
This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles. For more information about the manual page format, see the manual page for manpages(5). |
GETATTRLIST(2) BSD System Calls Manual GETATTRLIST(2) NAME getattrlist -- get file system attributes SYNOPSIS #include <sys/attr.h> #include <unistd.h> int getattrlist(const char* path, struct attrlist * attrList, void * attrBuf, size_t attrBufSize, unsigned long options); 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 system 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 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 ATTR_VOL_ATTRIBUTES for a discussion of how to determine whether a par-ticular particular 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, example, ple, ATTR_DIR_ENTRYCOUNT is usually expensive to calculate on non-HFS [Plus] volumes. If you don't need a particular attribute, you should not ask for it. The path parameter must reference a valid file system object. Read, write or execute permission of the object itself is not required, but all directories listed in the path name leading to the object must be search-able. searchable. able. The attrList parameter is a pointer to an attrlist structure, as defined by <sys/attr.h> (shown below). It determines what attributes are returned by the function. You are responsible for filling out all fields of this structure before calling the function. typedef u_int32_t attrgroup_t; struct attrlist { u_short bitmapcount; /* number of attr. bit sets in list */ u_int16_t reserved; /* (to maintain 4-byte alignment) */ attrgroup_t commonattr; /* common attribute group */ attrgroup_t volattr; /* volume attribute group */ attrgroup_t dirattr; /* directory attribute group */ attrgroup_t fileattr; /* file attribute group */ attrgroup_t forkattr; /* fork attribute group */ }; #define ATTR_BIT_MAP_COUNT 5 The fields of the attrlist structure are defined as follows. bitmapcount Number of attribute bit sets in the structure. In cur-rent current rent systems you must set this to ATTR_BIT_MAP_COUNT. reserved Reserved. You must set this to 0. commonattr A bit set that specifies the common attributes that you require. Common attributes relate to all types of file system objects. See below for a description of these attributes. volattr A bit set that specifies the volume attributes that you require. Volume attributes relate to volumes (that is, mounted file systems). See below for a description of these attributes. 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 sufficiently 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. FSOPT_NOFOLLOW If this bit is set, getattrlist() will not follow a sym-link symlink link if it occurs as the last component of path. ATTRIBUTE BUFFER The data returned in the buffer described by attrBuf and attrBufSize is formatted as follows. 1. The first element of the buffer is a u_int32_t that contains the overall length, in bytes, of the attributes returned. This size includes the length field itself. 2. Following the length field is a list of attributes. Each attribute is represented by a field of its type, where the type is given as part of the attribute description (below). 3. The attributes are placed into the attribute buffer in the order that they are described below. If the attribute is of variable length, it is represented in the list by an attrreference structure, as defined by <sys/attr.h> (shown below). typedef struct attrreference { long attr_dataoffset; size_t attr_length; } attrreference_t; This structure contains a 'pointer' to the variable length attribute data. The attr_length field is the length of the attribute data (in bytes). The attr_dataoffset field is the offset in bytes from the attrreference structure to the attribute data. This offset will always be a multiple of sizeof(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 attrreference_t, ( ( (char *) attrRef ) + attr_dataoffset ) > ( ( (char *) attrBuf ) + attrSize ) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that is, ( ( (char *) attrRef ) + attr_dataoffset + attr_datalength ) > ( ( (char *) attrBuf ) + attrSize ) ). If this happens you must increase the size of the buffer and call getattrlist() to get an accurate copy of the attribute. COMMON ATTRIBUTES Common attributes relate to all types of file system objects. The fol-lowing following lowing common attributes are defined. ATTR_CMN_NAME An attrreference structure containing the name of the file system object as UTF-8 encoded, null terminated C string. The attribute data length will not be greater than NAME_MAX + 1. ATTR_CMN_DEVID A dev_t containing the device number of the device on which this file system object's vol-ume volume ume is mounted. Equivalent to the st_dev field of the stat structure returned by stat(2). ATTR_CMN_FSID An fsid_t structure containing the file system identifier for the volume on which the file system object resides. Equivalent to the f_fsid field of the statfs structure returned by statfs(2). This value is not related to the file system ID from traditional Mac OS (for example, the filesystemID field of the FSVolumeInfo struc-ture structure ture returned by Carbon's FSGetVolumeInfo() function). On current versions of Mac OS X that value is synthesised by the Carbon File Manager. ATTR_CMN_OBJTYPE An fsobj_type_t that identifies the type of file system object. The values are taken from enum vtype in <sys/vnode.h>. ATTR_CMN_OBJTAG An fsobj_tag_t that identifies the type of file system containing the object. The values are taken from enum vtagtype in <sys/vnode.h>. ATTR_CMN_OBJID An fsobj_id_t structure that uniquely identi-fies identifies fies the file system object within its volume. The fid_generation 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 fid_objno field for the root directory (2) and the parent of root directory (1). This is not a required behaviour of this attribute. ATTR_CMN_OBJPERMANENTID An fsobj_id_t structure that uniquely identi-fies identifies fies the file system object within its volume. The fid_generation 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. ATTR_CMN_PAROBJID An fsobj_id_t structure that identifies the parent directory of the file system object. The fid_generation field of this structure will be zero for all non-root callers (effective UID not 0). Equivalent to the ATTR_CMN_OBJID attribute of the parent directory. This iden-tifier identifier tifier need not be persistent across an unmount/mount sequence. On a volume that supports hard links, a multi-ply multiply 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. ATTR_CMN_SCRIPT (read/write) A text_encoding_t containing a text encoding hint for the file system object's name. It is included to facilitate the loss-less lossless less round trip conversion of names between Unicode and traditional Mac OS script encod-ings. encodings. ings. The values are defined in <CarbonCore/TextCommon.h>. File systems that do not have an appropriate text encoding value should return kTextEncodingMacUnicode. See DTS Q&A 1173 "File Manager Text Encoding Hints". ATTR_CMN_CRTIME (read/write) A timespec structure containing the time that the file system object was cre-ated. created. ated. ATTR_CMN_MODTIME (read/write) A timespec structure containing the time that the file system object was last modified. Equivalent to the st_mtimespec field of the stat structure returned by stat(2). ATTR_CMN_CHGTIME (read/write) A timespec structure containing the time that the file system object's attributes were last modified. Equivalent to the st_ctimespec field of the stat structure returned by stat(2). ATTR_CMN_ACCTIME (read/write) A timespec structure containing the time that the file system object was last accessed. Equivalent to the st_atimespec field of the stat structure returned by stat(2). ATTR_CMN_BKUPTIME (read/write) A timespec structure containing the time that the file system object was last backed up. This value is for use by backup utilities. The file system stores but does not interpret the value. ATTR_CMN_FNDRINFO (read/write) 32 bytes of data for use by the Finder. Equivalent to the concatenation of a FileInfo structure and an ExtendedFileInfo structure (or, for directories, a FolderInfo structure and an ExtendedFolderInfo structure). These structures are defined in <CarbonCore/Finder.h>. This attribute is not byte swapped by the file system. The value of multibyte fields on disk is always big endian. When running on a little endian system (such as Darwin on x86), you must byte swap any multibyte fields. ATTR_CMN_OWNERID (read/write) A uid_t containing the owner of the file system object. Equivalent to the st_uid field of the stat structure returned by stat(2). ATTR_CMN_GRPID (read/write) A gid_t containing the group of the file system object. Equivalent to the st_gid field of the stat structure returned by stat(2). ATTR_CMN_ACCESSMASK (read/write) A u_int32_t containing the access permissions of the file system object. Equiva-lent Equivalent lent to the st_mode field of the stat structure returned by stat(2). ATTR_CMN_NAMEDATTRCOUNT A u_int32_t containing the number of named attributes of the file system object. ATTR_CMN_NAMEDATTRLIST 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. ATTR_CMN_FLAGS (read/write) A u_int32_t containing file flags. Equivalent to the st_flags field of the stat structure returned by stat(2). For more infor-mation information 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 ATTR_CMN_FLAGS. If its order was based on its bit position, it would be before the ATTR_CMN_NAMEDATTRCOUNT / ATTR_CMN_NAMEDATTRLIST pair, however, it is placed in the buffer after them. ATTR_CMN_USERACCESS A u_int32_t containing the effective permis-sions permissions 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 execute cute permission using R_OK, W_OK, and X_OK, respectively. See access(2) for more details. ATTR_CMN_FILEID A u_int64_t that uniquely identifies the file system object within its volume. ATTR_CMN_PARENTID A u_int64_t that identifies the parent direc-tory directory tory of the file system object. VOLUME ATTRIBUTES Volume attributes relate to volumes (that is, mounted file systems). The following volume attributes are defined. ATTR_VOL_INFO For reasons that are not at all obvious, you must set ATTR_VOL_INFO 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. ATTR_VOL_FSTYPE A u_int32_t containing the file system type. Equivalent to the f_type field of the statfs structure returned by statfs(2). Generally not a useful value. ATTR_VOL_SIGNATURE A u_int32_t containing the volume signature word. This value is unique within a given file system type and lets you distinguish between different volume formats handled by the same file system. See <CarbonCore/Files.h> for more details. ATTR_VOL_SIZE An off_t containing the total size of the vol-ume volume ume in bytes. ATTR_VOL_SPACEFREE An off_t containing the free space on the vol-ume volume ume in bytes. ATTR_VOL_SPACEAVAIL An off_t containing the space, in bytes, on the volume available to non-privileged processes. This is the free space minus the amount of space reserved by the system to prevent criti-cal critical cal disk exhaustion errors. Non-privileged programs, like a disk management tool, should use this value to display the space available to the user. ATTR_VOL_SPACEAVAIL is to ATTR_VOL_SPACEFREE as f_bavail is to f_bfree in statfs(2). ATTR_VOL_MINALLOCATION An off_t containing the minimum allocation size on the volume in bytes. If you create a file containing one byte, it will consume this much space. ATTR_VOL_ALLOCATIONCLUMP An off_t containing the allocation clump size on the volume, in bytes. As a file is extended, the file system will attempt to allo-cate allocate cate this much space each time in order to reduce fragmentation. ATTR_VOL_IOBLOCKSIZE A u_int32_t containing the optimal block size when reading or writing data. Equivalent to the f_iosize field of the statfs structure returned by statfs(2). ATTR_VOL_OBJCOUNT A u_int32_t containing the number of file sys-tem system tem objects on the volume. ATTR_VOL_FILECOUNT A u_int32_t containing the number of files on the volume. ATTR_VOL_DIRCOUNT A u_int32_t containing the number of directo-ries directories ries on the volume. ATTR_VOL_MAXOBJCOUNT A u_int32_t containing the maximum number of file system objects that can be stored on the volume. ATTR_VOL_MOUNTPOINT An attrreference structure containing the path to the volume's mount point as a UTF-8 encoded, null terminated C string. The attribute data length will not be greater than MAXPATHLEN. Equivalent to the f_mntonname field of the statfs structure returned by statfs(2). ATTR_VOL_NAME (read/write) An attrreference structure con-taining containing taining the name of the volume as a UTF-8 encoded, null terminated C string. The attribute data length will not be greater than NAME_MAX + 1. This attribute is only read/write if the VOL_CAP_INT_VOL_RENAME bit is set in the volume capabilities (see below). ATTR_VOL_MOUNTFLAGS A u_int32_t containing the volume mount flags. This is a copy of the value passed to the flags parameter of mount(2) when the volume was mounted. Equivalent to the f_flags field of the statfs structure returned by statfs(2). ATTR_VOL_MOUNTEDDEVICE An attrreference structure that returns the same value as the f_mntfromname field of the statfs structure returned by statfs(2). For local volumes this is the path to the device on which the volume is mounted as a UTF-8 encoded, null terminated C string. For network volumes, this is a unique string that identifies the mount. The attribute data length will not be greater than MAXPATHLEN. ATTR_VOL_ENCODINGSUSED An unsigned long long containing a bitmap of the text encodings used on this volume. For more information about this, see the discussion of encodingsBitmap in DTS Technote 1150 "HFS Plus Volume Format". ATTR_VOL_CAPABILITIES A vol_capabilities_attr_t structure describing the optional features supported by this volume. See below for a discussion of volume capabili-ties. capabilities. ties. ATTR_VOL_ATTRIBUTES A vol_attributes_attr_t structure describing the attributes supported by this volume. This structure is discussed below, along with volume capabilities. DIRECTORY ATTRIBUTES The following directory attributes are defined. ATTR_DIR_LINKCOUNT A u_int32_t containing the number of hard links to the directory; this does not include the historical "." and ".." entries. For filesys-tems filesystems tems that do not support hard links to directo-ries, directories, ries, this value will be 1. ATTR_DIR_ENTRYCOUNT A u_int32_t containing the number of file sys-tem system tem objects in the directory, not including any synthetic items. ATTR_DIR_MOUNTSTATUS A u_int32_t containing flags describing what's mounted on the directory. Currently the only flag defined is DIR_MNTSTATUS_MNTPOINT, which indicates that there is a file system mounted on this directory. Due to a bug (r. 3502822), this flag is never set on current system. FILE ATTRIBUTES The following file attributes are defined. ATTR_FILE_LINKCOUNT A u_int32_t containing the number of hard links to this file. Equivalent to the st_nlink field of the stat structure returned by stat(2). ATTR_FILE_TOTALSIZE An off_t containing the total number of bytes in all forks of the file (the logical size). ATTR_FILE_ALLOCSIZE An off_t containing a count of the bytes on disk used by all of the file's forks (the phys-ical physical ical size). ATTR_FILE_IOBLOCKSIZE A u_int32_t containing the optimal block size when reading or writing this file's data. ATTR_FILE_CLUMPSIZE A u_int32_t containing the allocation clump size for this file, in bytes. As the file is extended, the file system will attempt to allo-cate allocate cate this much space each time in order to reduce fragmentation. This value applies to the data fork. ATTR_FILE_DEVTYPE (read/write) A u_int32_t containing the device type for a special device file. Equivalent to the st_rdev field of the stat structure returned by stat(2). ATTR_FILE_FILETYPE A u_int32_t that whose value is reserved. Clients should ignore its value. New volume format implementations should not support this attribute. ATTR_FILE_FORKCOUNT A u_int32_t containing the number of forks in the file. No built-in file systems on Mac OS X currently support forks other than the data and resource fork. ATTR_FILE_FORKLIST An attrreference structure containing a list of named forks of the file. No built-in file sys-tems systems 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. ATTR_FILE_DATALENGTH An off_t containing the length of the data fork in bytes (the logical size). ATTR_FILE_DATAALLOCSIZE An off_t containing a count of the bytes on disk used by the data fork (the physical size). ATTR_FILE_DATAEXTENTS An extentrecord array for the data fork. The array contains eight diskextent structures which represent the first eight extents of the fork. This attributes exists for compatibility rea-sons. reasons. sons. New clients should not use this attribute. Rather, they should use the F_LOG2PHYS command in fcntl(2). In current implementations the value may not be entirely accurate for a variety of reasons. ATTR_FILE_RSRCLENGTH An off_t containing the length of the resource fork in bytes (the logical size). ATTR_FILE_RSRCALLOCSIZE An off_t containing a count of the bytes on disk used by the resource fork (the physical size). ATTR_FILE_RSRCEXTENTS An extentrecord array for the resource fork. The array contains eight diskextent structures which represent the first eight extents of the fork. See also ATTR_FILE_DATAEXTENTS. FORK ATTRIBUTES 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. ATTR_FORK_TOTALSIZE An off_t containing the length of the fork in bytes (the logical size). ATTR_FORK_ALLOCSIZE An off_t 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 volume 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 ATTR_VOL_CAPABILITIES attribute returns a vol_capabilities_attr_t structure (shown below) that indicates which features are supported by the volume. typedef u_int32_t vol_capabilities_set_t[4]; #define VOL_CAPABILITIES_FORMAT 0 #define VOL_CAPABILITIES_INTERFACES 1 #define VOL_CAPABILITIES_RESERVED1 2 #define VOL_CAPABILITIES_RESERVED2 3 typedef struct vol_capabilities_attr { vol_capabilities_set_t capabilities; vol_capabilities_set_t valid; } vol_capabilities_attr_t; The structure contains two fields, capabilities and valid. Each consists of an array of four elements. The arrays are indexed by the following values. VOL_CAPABILITIES_FORMAT This element contains information about the volume format. See VOL_CAP_FMT_PERSISTENTOBJECTIDS and so on, below. VOL_CAPABILITIES_INTERFACES This element contains information about which optional functions are supported by the volume format implementation. See VOL_CAP_INT_SEARCHFS and so on, below. VOL_CAPABILITIES_RESERVED1 Reserved. A file system implementation should set this element to zero. A client program should ignore this ele-ment. element. ment. VOL_CAPABILITIES_RESERVED2 Reserved. A file system implementation should set this element to zero. A client program should ignore this ele-ment. element. 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 contents tents of the corresponding bit in the capabilities field is valid. The capabilities field contains bit sets that indicate whether a particu-lar particular lar feature is implemented by this volume format. The following bits are defined in the first element (indexed by VOL_CAPABILITIES_FORMAT) of the capabilities and valid fields of the vol_capabilities_attr_t structure. VOL_CAP_FMT_PERSISTENTOBJECTIDS If this bit is set the volume format supports persistent object identifiers and can look up file system objects by their IDs. See ATTR_CMN_OBJPERMANENTID for details about how to obtain these identifiers. VOL_CAP_FMT_SYMBOLICLINKS If this bit is set the volume format supports symbolic links. VOL_CAP_FMT_HARDLINKS If this bit is set the volume format supports hard links. VOL_CAP_FMT_JOURNAL If this bit is set the volume format supports a journal used to speed recov-ery recovery 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). VOL_CAP_FMT_JOURNAL_ACTIVE If this bit is set the volume is cur-rently currently rently using a journal for speedy recov-ery recovery ery after an unplanned restart. This bit can be set only if VOL_CAP_FMT_JOURNAL is also set. Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_FMT_NO_ROOT_TIMES If this bit is set the volume format does not store reliable times for the root directory, so you should not depend on them to detect changes, identify vol-umes volumes umes across unmount/mount, and so on. Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_FMT_SPARSE_FILES If this bit is set the volume format supports sparse files, that is, files which can have 'holes' that have never been written to, and thus do not consume space on disk. A sparse file may have an allocated size on disk that is less than its logical length (that is, ATTR_FILE_ALLOCSIZE < ATTR_FILE_TOTALSIZE ). Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_FMT_ZERO_RUNS For security reasons, parts of a file (runs) that have never been written to must appear to contain zeroes. When this bit is set, the volume keeps track of allocated but unwritten runs of a file so that it can substitute zeroes without actually writing zeroes to the media. This provides performance simi- lar to sparse files, but not the space savings. Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_FMT_CASE_SENSITIVE If this bit is set the volume format treats upper and lower case characters in file and directory names as differ-ent. different. 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). VOL_CAP_FMT_CASE_PRESERVING If this bit is set the volume format preserves the case of file and directory names. Otherwise the volume may change the case of some characters (typically making them all upper or all lower case). A volume that sets VOL_CAP_FMT_CASE_SENSITIVE must also set VOL_CAP_FMT_CASE_PRESERVING. Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_FMT_FAST_STATFS This bit is used as a hint to upper lay-ers layers ers (specifically the Carbon File Man-ager) Manager) 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 network work transaction to satisfy statfs(2) should not set this bit. Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_FMT_2TB_FILESIZE If this bit is set the volume format supports file sizes 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 VOL_CAPABILITIES_INTERFACES) of the capabilities and valid fields of the vol_capabilities_attr_t structure. VOL_CAP_INT_SEARCHFS If this bit is set the volume format implementation supports searchfs(2). VOL_CAP_INT_ATTRLIST If this bit is set the volume format implementation supports getattrlist() and setattrlist(2). VOL_CAP_INT_NFSEXPORT If this bit is set the volume format implementation allows this volume to be exported via NFS. VOL_CAP_INT_READDIRATTR If this bit is set the volume format implementation supports getdirentriesattr(2). VOL_CAP_INT_EXCHANGEDATA If this bit is set the volume format implementation supports exchangedata(2). Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_INT_COPYFILE If this bit is set the volume format implementation supports the (private and undocumented) copyfile() function. Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_INT_ALLOCATE If this bit is set the volume format implementation supports the F_PREALLOCATE selector of fcntl(2). Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_INT_VOL_RENAME If this bit is set the volume format implementation allows you to modify the volume name using setattrlist(2). Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_INT_ADVLOCK If this bit is set the volume format implementation supports advisory lock-ing, locking, ing, that is, the F_GETLK, F_SETLK, and F_SETLKW selectors to fcntl(2). Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_INT_FLOCK If this bit is set the volume format implementation supports whole file locks. This includes flock(2) and the O_EXLOCK and O_SHLOCK flags to open(2). Introduced with Darwin 7.0 (Mac OS X version 10.3). VOL_CAP_INT_EXTENDED_SECURITY If this bit is set the volume format implementation supports extended secu-rity security rity controls (ACLs). Introduced with Darwin 8.0 (Mac OS X version 10.4). VOL_CAP_INT_USERACCESS If this bit is set the volume format implementation supports the ATTR_CMN_USERACCESS attribute. Introduced with Darwin 8.0 (Mac OS X version 10.4). A volume can also report which attributes it supports. This information is returned by the ATTR_VOL_ATTRIBUTES attribute, which returns a vol_attributes_attr_t structure (shown below). typedef struct attribute_set { attrgroup_t commonattr; /* common attribute group */ attrgroup_t volattr; /* volume attribute group */ attrgroup_t dirattr; /* directory attribute group */ attrgroup_t fileattr; /* file attribute group */ attrgroup_t forkattr; /* fork attribute group */ } attribute_set_t; typedef struct vol_attributes_attr { attribute_set_t validattr; attribute_set_t nativeattr; } vol_attributes_attr_t; The validattr field consists of a number of bit sets that indicate whether an attribute is supported by the volume format implementation. The nativeattr is similar except that the bit sets indicate whether an attribute is supported natively by the volume format. An attribute is supported natively if the volume format implementation does not have to do any complex conversions to access the attribute. For example, a vol-ume volume 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. format. mat. In that case, the ATTR_VOL_ATTRIBUTES attribute would return ATTR_CMN_OBJPERMANENTID set in the validattr field of the vol_attributes_attr_t, but not in the nativeattr field. RETURN VALUES Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. COMPATIBILITY Not all volumes support getattrlist(). The best way to test whether a volume supports this function is to simply call it and check the error result. getattrlist() will return ENOTSUP if it is not supported on a particular volume. The getattrlist() function has been undocumented for more than two years. In that time a number of volume format implementations have been created without a proper specification for the behaviour of this routine. You may encounter volume format implementations with slightly different be-haviour behaviour haviour than what is described here. Your program is expected to be tol-erant tolerant 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. ERRORS getattrlist() will fail if: [ENOTSUP] The volume does not support getattrlist(). [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a path name exceeded NAME_MAX charac-ters, characters, ters, or an entire path name exceeded PATH_MAX charac-ters. characters. 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 translating ing the pathname. [EFAULT] path, attrList or attrBuf points to an invalid address. [EINVAL] The bitmapcount field of attrList is not ATTR_BIT_MAP_COUNT. [EINVAL] You requested an invalid attribute. [EINVAL] You requested an attribute that is not supported for this file system object. [EINVAL] You requested volume attributes and directory or file attributes. [EINVAL] You requested volume attributes but path does not ref-erence reference 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 ATTR_VOL_INFO in the volattr field, even though it generates no result in the attribute buffer. The order that attributes are stored in the attribute buffer almost invariably matches the order of attribute mask bit values. For example, ATTR_CMN_NAME (0x00000001) comes before ATTR_CMN_DEVID (0x00000002) because its value is smaller. However, you can not rely on this ordering because there is one key exception: ATTR_CMN_FLAGS is placed after the ATTR_CMN_NAMEDATTRCOUNT / ATTR_CMN_NAMEDATTRLIST 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 compatibility 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 <assert.h> #include <stdio.h> #include <string.h> #include <sys/attr.h> #include <sys/errno.h> #include <unistd.h> #include <sys/vnode.h> typedef struct attrlist attrlist_t; struct FInfoAttrBuf { u_int32_t length; fsobj_type_t objType; char finderInfo[32]; }; typedef struct FInfoAttrBuf FInfoAttrBuf; static int FInfoDemo(const char *path) { int err; attrlist_t attrList; FInfoAttrBuf attrBuf; memset(&attrList, 0, sizeof(attrList)); attrList.bitmapcount = ATTR_BIT_MAP_COUNT; attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO; err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0); if (err != 0) { err = errno; } if (err == 0) { assert(attrBuf.length == sizeof(attrBuf)); printf("Finder information for %s:\n", path); switch (attrBuf.objType) { case VREG: printf("file type = '%.4s'\n", &attrBuf.finderInfo[0]); printf("file creator = '%.4s'\n", &attrBuf.finderInfo[4]); break; case VDIR: printf("directory\n"); break; default: printf("other object type, %d\n", attrBuf.objType); break; } } return err; } The following code is an alternative implementation that uses nested structures to group the related attributes. #include <assert.h> #include <stdio.h> #include <stddef.h> #include <string.h> #include <sys/attr.h> #include <sys/errno.h> #include <unistd.h> #include <sys/vnode.h> typedef struct attrlist attrlist_t; struct FInfo2CommonAttrBuf { fsobj_type_t objType; char finderInfo[32]; }; typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf; struct FInfo2AttrBuf { u_int32_t length; FInfo2CommonAttrBuf common; }; typedef struct FInfo2AttrBuf FInfo2AttrBuf; static int FInfo2Demo(const char *path) { int err; attrlist_t attrList; FInfo2AttrBuf attrBuf; memset(&attrList, 0, sizeof(attrList)); attrList.bitmapcount = ATTR_BIT_MAP_COUNT; attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO; err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0); if (err != 0) { err = errno; } if (err == 0) { assert(attrBuf.length == sizeof(attrBuf)); printf("Finder information for %s:\n", path); switch (attrBuf.common.objType) { case VREG: printf( "file type = '%.4s'\n", &attrBuf.common.finderInfo[0] ); printf( "file creator = '%.4s'\n", &attrBuf.common.finderInfo[4] ); break; case VDIR: printf("directory\n"); break; default: printf( "other object type, %d\n", attrBuf.common.objType ); break; } } return err; } The following example shows how to deal with variable length attributes. It assumes that the volume specified by path supports the necessary attributes. #include <assert.h> #include <stdio.h> #include <stddef.h> #include <string.h> #include <sys/attr.h> #include <sys/errno.h> #include <unistd.h> #include <sys/vnode.h> typedef struct attrlist attrlist_t; struct VolAttrBuf { u_int32_t length; u_int32_t fileCount; u_int32_t dirCount; attrreference_t mountPointRef; attrreference_t volNameRef; char mountPointSpace[MAXPATHLEN]; char volNameSpace[MAXPATHLEN]; }; typedef struct VolAttrBuf VolAttrBuf; static int VolDemo(const char *path) { int err; attrlist_t attrList; VolAttrBuf attrBuf; memset(&attrList, 0, sizeof(attrList)); attrList.bitmapcount = ATTR_BIT_MAP_COUNT; attrList.volattr = ATTR_VOL_INFO | ATTR_VOL_FILECOUNT | ATTR_VOL_DIRCOUNT | ATTR_VOL_MOUNTPOINT | ATTR_VOL_NAME; err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0); if (err != 0) { err = errno; } if (err == 0) { assert(attrBuf.length > offsetof(VolAttrBuf, mountPointSpace)); assert(attrBuf.length <= sizeof(attrBuf)); printf("Volume information for %s:\n", path); printf("ATTR_VOL_FILECOUNT: %lu\n", attrBuf.fileCount); printf("ATTR_VOL_DIRCOUNT: %lu\n", attrBuf.dirCount); printf( "ATTR_VOL_MOUNTPOINT: %.*s\n", (int) attrBuf.mountPointRef.attr_length, ( ((char *) &attrBuf.mountPointRef) + attrBuf.mountPointRef.attr_dataoffset ) ); printf( "ATTR_VOL_NAME: %.*s\n", (int) attrBuf.volNameRef.attr_length, ( ((char *) &attrBuf.volNameRef) + attrBuf.volNameRef.attr_dataoffset ) ); } return err; } 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 |