Mac Developer Library Developer
Search

 

This manual page is part of Xcode Tools version 5.0

To obtain these tools:

If you are running a version of Xcode Tools other than 5.0, view the documentation locally:

  • In Xcode

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.




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

NAME
     getattrlist, fgetattrlist -- get file system attributes

SYNOPSIS
     #include <sys/attr.h>
     #include <unistd.h>

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

     int
     fgetattrlist(int fd, struct attrlist * attrList, void * attrBuf, size_t attrBufSize,
         unsigned long options);

DESCRIPTION
     The getattrlist() function returns attributes (that is, metadata) of file system objects.
     getattrlist() works on the file system object named by path, while fgetattrlist() works on the provided
     file descriptor fd.  You can think of getattrlist() as a seriously enhanced version of stat(2).  The
     functions return attributes about the specified file system object into the buffer specified by attrBuf
     and attrBufSize.  The attrList parameter determines what attributes are returned.  The options parame-ter parameter
     ter lets you control specific aspects of the function's behavior.

     The getattrlist() and fgetattrlist() functions are only supported by certain volume format implementa-tions. implementations.
     tions.  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 the calls.

     Not all volumes support all attributes.  See the discussion of ATTR_VOL_ATTRIBUTES for a discussion of
     how to determine whether a particular volume supports a particular attribute.

     Furthermore, you should only request the attributes that you need.  Some attributes are expensive to
     calculate on some volume formats.  For example, ATTR_DIR_ENTRYCOUNT is usually expensive to calculate
     on non-HFS [Plus] volumes.  If you don't need a particular attribute, you should not ask for it.

     The path parameter must reference a valid file system object.  Read, write or execute permission of the
     object itself is not required, but all directories listed in the path name leading to the object must
     be searchable.

     The attrList parameter is a pointer to an attrlist structure, as defined by <sys/attr.h> (shown below).
     It determines what attributes are returned by the function.  You are responsible for filling out all
     fields of this structure before calling the function.

     typedef u_int32_t attrgroup_t;

     struct attrlist {
         u_short     bitmapcount; /* number of attr. bit sets in list */
         u_int16_t   reserved;    /* (to maintain 4-byte alignment) */
         attrgroup_t commonattr;  /* common attribute group */
         attrgroup_t volattr;     /* volume attribute group */
         attrgroup_t dirattr;     /* directory attribute group */
         attrgroup_t fileattr;    /* file attribute group */
         attrgroup_t forkattr;    /* fork attribute group */
     };
     #define ATTR_BIT_MAP_COUNT 5

     The fields of the attrlist structure are defined as follows.

     bitmapcount     Number of attribute bit sets in the structure.  In current systems you must set this to
                     ATTR_BIT_MAP_COUNT.

     reserved        Reserved.  You must set this to 0.

     commonattr      A bit set that specifies the common attributes that you require.  Common attributes
                     relate to all types of file system objects.  See below for a description of these
                     attributes.

     volattr         A bit set that specifies the volume attributes that you require.  Volume attributes
                     relate to volumes (that is, mounted file systems).  See below for a description of
                     these attributes.  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 val-ues. values.
     ues.  The format of this buffer is sufficiently complex that its description requires a separate sec-tion section
     tion (see below).  The initial contents of this buffer are ignored.

     The options parameter is a bit set that controls the behaviour of the functions.  The following option
     bits are defined.

     FSOPT_NOFOLLOW          If this bit is set, getattrlist() will not follow a symlink if it occurs as the
                             last component of path.

     FSOPT_REPORT_FULLSIZE   The size of the attributes reported (in the first u_int32_t field in the
                             attribute buffer) will be the size needed to hold all the requested attributes;
                             if not set, only the attributes actually returned will be reported.  This
                             allows the caller to determine if any truncation occurred.

     FSOPT_PACK_INVAL_ATTRS  If this is bit is set, then all requested attributes, even ones that are not
                             supported by the object or file system, will be returned.  Default values will
                             be used for the invalid ones.  Requires that ATTR_CMN_RETURNED_ATTRS be
                             requested.

ATTRIBUTE BUFFER
     The data returned in the buffer described by attrBuf and attrBufSize is formatted as follows.

     1.   The first element of the buffer is a u_int32_t that contains the overall length, in bytes, of the
          attributes returned.  This size includes the length field itself.

     2.   Following the length field is a list of attributes.  Each attribute is represented by a field of
          its type, where the type is given as part of the attribute description (below).

     3.   The attributes are placed into the attribute buffer in the order that they are described below.

     4.   Each attribute is aligned to a 4-byte boundary (including 64-bit data types).

     If the attribute is of variable length, it is represented in the list by an attrreference structure, as
     defined by <sys/attr.h> (shown below).

     typedef struct attrreference {
         int32_t        attr_dataoffset;
         u_int32_t      attr_length;
     } attrreference_t;

     This structure contains a 'pointer' to the variable length attribute data.  The attr_length field is
     the length of the attribute data (in bytes).  The attr_dataoffset field is the offset in bytes from the
     attrreference structure to the attribute data.  This offset will always be a multiple of
     sizeof(u_int32_t) bytes, so you can safely access common data types without fear of alignment excep-tions. exceptions.
     tions.

     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 pos-sible possible
     sible for the attribute data to start beyond the end of the attribute buffer (that is, if attrRef is a
     pointer to the attrreference_t, ( ( (char *) attrRef ) + attr_dataoffset ) > ( ( (char *) attrBuf ) +
     attrSize ) ) or, indeed, for the attribute data to extend beyond the end of the attribute buffer (that
     is, ( ( (char *) attrRef ) + attr_dataoffset + attr_datalength ) > ( ( (char *) attrBuf ) + attrSize )
     ).  If this happens you must increase the size of the buffer and call getattrlist() to get an accurate
     copy of the attribute.

COMMON ATTRIBUTES
     Common attributes relate to all types of file system objects.  The following common attributes are
     defined.

     ATTR_CMN_RETURNED_ATTRS   An attribute_set_t structure which is used to report which of the requested
                               attributes were actually returned. This attribute, when requested, will
                               always be the first attribute returned. By default, unsupported attributes
                               will be skipped (i.e. not packed into the output buffer). This behavior can
                               be over-ridden using the FSOPT_PACK_INVAL_ATTRS option flag. Only
                               getattrlist(2) supports this attribute ( getdirentriesattr(2) and searchfs(2)
                               do not support it ).

     ATTR_CMN_NAME             An attrreference structure containing the name of the file system object as
                               UTF-8 encoded, null terminated C string.  The attribute data length will not
                               be greater than NAME_MAX + 1 characters, which is NAME_MAX * 3 + 1 bytes (as
                               one UTF-8-encoded character may take up to three bytes).

     ATTR_CMN_DEVID            A dev_t containing the device number of the device on which this file system
                               object's volume is mounted.  Equivalent to the st_dev field of the stat
                               structure returned by stat(2).

     ATTR_CMN_FSID             An fsid_t structure containing the file system identifier for the volume on
                               which the file system object resides.  Equivalent to the f_fsid field of the
                               statfs structure returned by statfs(2).

                               This value is not related to the file system ID from traditional Mac OS (for
                               example, the filesystemID field of the FSVolumeInfo structure 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 identifies 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 identifies 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 sys-tem system
                               tem 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 identifier need not be persistent
                               across an unmount/mount sequence.

                               On a volume that supports hard links, a multiply 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 lossless round trip
                               conversion of names between Unicode and traditional Mac OS script encodings.
                               The values are defined in <CarbonCore/TextCommon.h>.  File systems that do
                               not have an appropriate text encoding value should return kTextEncodingMacU-nicode. kTextEncodingMacUnicode.
                               nicode.  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 created.

     ATTR_CMN_MODTIME          (read/write) A timespec structure containing the time that the file system
                               object was last modified.  Equivalent to the st_mtimespec field of the stat
                               structure returned by stat(2).

     ATTR_CMN_CHGTIME          (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 con-catenation concatenation
                               catenation 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 multi-byte multibyte
                               byte 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.  Equiva-lent Equivalent
                               lent 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.  Equiva-lent Equivalent
                               lent to the st_gid field of the stat structure returned by stat(2).

     ATTR_CMN_ACCESSMASK       (read/write) A u_int32_t containing the access permissions of the file system
                               object.  Equivalent to the st_mode field of the stat structure returned by
                               stat(2).  Only the permission bits of st_mode are valid; other bits should be
                               ignored, e.g., by masking with ~S_IFMT.

     ATTR_CMN_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 information about
                               these flags, see chflags(2).

                               The order that attributes are placed into the attribute buffer almost invari-ably invariably
                               ably 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 permissions of the current user (the
                               calling process's effective UID) for this file system object.  You can test
                               for read, write, and execute permission using R_OK, W_OK, and X_OK, respec-tively. respectively.
                               tively.  See access(2) for more details.

     ATTR_CMN_EXTENDED_SECURITY
                               A variable-length object (thus an attrreference structure) containing a
                               kauth_filesec structure, of which only the ACL entry is used.

     ATTR_CMN_UUID             A guid_t of the owner of the file system object.  Analoguous to
                               ATTR_CMN_OWNERID.

     ATTR_CMN_GRPUUID          A guid_t of the group to which the file system object belongs.  Analoguous to
                               ATTR_CMN_GRPID.

     ATTR_CMN_FILEID           A u_int64_t that uniquely identifies the file system object within its vol-ume. volume.
                               ume.

     ATTR_CMN_PARENTID         A u_int64_t that identifies the parent directory of the file system object.

     ATTR_CMN_FULLPATH         An attrreference structure containing the full path (resolving all symlinks)
                               to the file system object as a UTF-8 encoded, null terminated C string.  The
                               attribute data length will not be greater than PATH_MAX. Inconsistent behav-ior behavior
                               ior may be observed when this attribute is requested on hard-linked items,
                               particularly when the file system does not support ATTR_CMN_PARENTID
                               natively. Callers should be aware of this when requesting the full path of a
                               hard-linked item.

     ATTR_CMN_ADDEDTIME        A timespec that contains the time that the file system object was created or
                               renamed into its containing directory.  Note that inconsistent behavior may
                               be observed when this attribute is requested on hard-linked items.

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 volume in bytes.

     ATTR_VOL_SPACEFREE        An off_t containing the free space on the volume in bytes.

     ATTR_VOL_SPACEAVAIL       An off_t containing the space, in bytes, on the volume available to non-priv-ileged non-privileged
                               ileged processes.  This is the free space minus the amount of space reserved
                               by the system to prevent critical disk exhaustion errors.  Non-privileged
                               programs, like a disk management tool, should use this value to display the
                               space available to the user.

                               ATTR_VOL_SPACEAVAIL is to ATTR_VOL_SPACEFREE as f_bavail is to f_bfree in
                               statfs(2).

     ATTR_VOL_MINALLOCATION    An off_t containing the minimum allocation size on the volume in bytes.  If
                               you create a file containing one byte, it will consume this much space.

     ATTR_VOL_ALLOCATIONCLUMP  An off_t containing the allocation clump size on the volume, in bytes.  As a
                               file is extended, the file system will attempt to allocate this much space
                               each time in order to reduce fragmentation.

     ATTR_VOL_IOBLOCKSIZE      A u_int32_t containing the optimal block size when reading or writing data.
                               Equivalent to the f_iosize field of the statfs structure returned by
                               statfs(2).

     ATTR_VOL_OBJCOUNT         A u_int32_t containing the number of file system objects on the volume.

     ATTR_VOL_FILECOUNT        A u_int32_t containing the number of files on the volume.

     ATTR_VOL_DIRCOUNT         A u_int32_t containing the number of directories on the volume.

     ATTR_VOL_MAXOBJCOUNT      A u_int32_t containing the maximum number of file system objects that can be
                               stored on the volume.

     ATTR_VOL_MOUNTPOINT       An attrreference structure containing the path to the volume's mount point as
                               a UTF-8 encoded, null terminated C string.  The attribute data length will
                               not be greater than MAXPATHLEN.  Equivalent to the f_mntonname field of the
                               statfs structure returned by statfs(2).

     ATTR_VOL_NAME             (read/write) An attrreference structure containing the name of the volume as
                               a UTF-8 encoded, null terminated C string.  The attribute data length will
                               not be greater than NAME_MAX + 1.

                               This attribute is only read/write if the VOL_CAP_INT_VOL_RENAME bit is set in
                               the volume capabilities (see below).

     ATTR_VOL_MOUNTFLAGS       A u_int32_t containing the volume mount flags.  This is a copy of the value
                               passed to the flags parameter of mount(2) when the volume was mounted.
                               Equivalent to the f_flags field of the statfs structure returned by
                               statfs(2).

     ATTR_VOL_MOUNTEDDEVICE    An attrreference structure that returns the same value as the f_mntfromname
                               field of the statfs structure returned by statfs(2).  For local volumes this
                               is the path to the device on which the volume is mounted as a UTF-8 encoded,
                               null terminated C string.  For network volumes, this is a unique string that
                               identifies the mount.  The attribute data length will not be greater than
                               MAXPATHLEN.

     ATTR_VOL_ENCODINGSUSED    An unsigned long long containing a bitmap of the text encodings used on this
                               volume.  For more information about this, see the discussion of
                               encodingsBitmap in DTS Technote 1150 "HFS Plus Volume Format".

     ATTR_VOL_CAPABILITIES     A vol_capabilities_attr_t structure describing the optional features sup-ported supported
                               ported by this volume.  See below for a discussion of volume capabilities.

     ATTR_VOL_UUID             A uuid_t containing the file system UUID.  Typically this will be a version 5
                               UUID.

     ATTR_VOL_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 file systems that do
                               not support hard links to directories, this value will be 1.

     ATTR_DIR_ENTRYCOUNT       A u_int32_t containing the number of file system objects in the directory,
                               not including any synthetic items.  The historical "." and ".." entries are
                               also excluded from this count.

     ATTR_DIR_MOUNTSTATUS      A u_int32_t containing flags describing what's mounted on the directory.
                               Currently the only flag defined is DIR_MNTSTATUS_MNTPOINT, which indicates
                               that there is a file system mounted on this directory.

     Requested directory attributes are not returned for file system objects that are not directories.

FILE ATTRIBUTES
     The following file attributes are defined.

     ATTR_FILE_LINKCOUNT       A u_int32_t containing the number of hard links to this file.  Equivalent to
                               the st_nlink field of the stat structure returned by stat(2).

     ATTR_FILE_TOTALSIZE       An off_t containing the total number of bytes in all forks of the file (the
                               logical size).

     ATTR_FILE_ALLOCSIZE       An off_t containing a count of the bytes on disk used by all of the file's
                               forks (the physical size).

     ATTR_FILE_IOBLOCKSIZE     A u_int32_t containing the optimal block size when reading or writing this
                               file's data.

     ATTR_FILE_CLUMPSIZE       A u_int32_t containing the allocation clump size for this file, in bytes.  As
                               the file is extended, the file system will attempt to allocate this much
                               space each time in order to reduce fragmentation.  This value applies to the
                               data fork.

     ATTR_FILE_DEVTYPE         (read/write) A u_int32_t containing the device type for a special device
                               file.  Equivalent to the st_rdev field of the stat structure returned by
                               stat(2).

     ATTR_FILE_FILETYPE        A u_int32_t that whose value is reserved.  Clients should ignore its value.
                               New volume format implementations should not support this attribute.

     ATTR_FILE_FORKCOUNT       A u_int32_t containing the number of forks in the file.  No built-in file
                               systems on Mac OS X currently support forks other than the data and resource
                               fork.

     ATTR_FILE_FORKLIST        An attrreference structure containing a list of named forks of the file.  No
                               built-in file systems on Mac OS X currently support forks other than the data
                               and resource fork.  Because of this, the structure of this attribute's value
                               is not yet defined.

     ATTR_FILE_DATALENGTH      An off_t containing the length of the data fork in bytes (the logical size).

     ATTR_FILE_DATAALLOCSIZE   An off_t containing a count of the bytes on disk used by the data fork (the
                               physical size).

     ATTR_FILE_DATAEXTENTS     An extentrecord array for the data fork.  The array contains eight diskextent
                               structures which represent the first eight extents of the fork.

                               This attributes exists for compatibility reasons.  New clients should not use
                               this attribute.  Rather, they should use the F_LOG2PHYS command in fcntl(2).

                               In current implementations the value may not be entirely accurate for a vari-ety variety
                               ety of reasons.

     ATTR_FILE_RSRCLENGTH      An off_t containing the length of the resource fork in bytes (the logical
                               size).

     ATTR_FILE_RSRCALLOCSIZE   An off_t containing a count of the bytes on disk used by the resource fork
                               (the physical size).

     ATTR_FILE_RSRCEXTENTS     An extentrecord array for the resource fork.  The array contains eight
                               diskextent structures which represent the first eight extents of the fork.

                               See also ATTR_FILE_DATAEXTENTS.

     File attributes are used for any file system object that is not a directory, not just ordinary files.
     Requested file attributes are not returned for file system objects that are directories.

FORK ATTRIBUTES
     Fork attributes relate to the actual data in the file, which can be held in multiple named contiguous
     ranges, or forks.  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 physi-cal physical
                               cal size).

     Fork attributes are not properly implemented by any current Mac OS X volume format implementation.  We
     strongly recommend that client programs do not request fork attributes.  If you are implementing a vol-ume volume
     ume 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 vol-ume. volume.
     ume.

     typedef u_int32_t vol_capabilities_set_t[4];

     #define VOL_CAPABILITIES_FORMAT     0
     #define VOL_CAPABILITIES_INTERFACES 1
     #define VOL_CAPABILITIES_RESERVED1  2
     #define VOL_CAPABILITIES_RESERVED2  3

     typedef struct vol_capabilities_attr {
         vol_capabilities_set_t capabilities;
         vol_capabilities_set_t valid;
     } vol_capabilities_attr_t;

     The structure contains two fields, capabilities and valid.  Each consists of an array of four elements.
     The arrays are indexed by the following values.

     VOL_CAPABILITIES_FORMAT          This element contains information about the volume format.  See
                                      VOL_CAP_FMT_PERSISTENTOBJECTIDS and so on, below.

     VOL_CAPABILITIES_INTERFACES      This element contains information about which optional functions are
                                      supported by the volume format implementation.  See
                                      VOL_CAP_INT_SEARCHFS and so on, below.

     VOL_CAPABILITIES_RESERVED1       Reserved.  A file system implementation should set this element to
                                      zero.  A client program should ignore this element.

     VOL_CAPABILITIES_RESERVED2       Reserved.  A file system implementation should set this element to
                                      zero.  A client program should ignore this element.

     The valid field contains bit sets that indicate which flags are known to the volume format implementa-tion. implementation.
     tion.  Each bit indicates whether the contents of the corresponding bit in the capabilities field is
     valid.

     The capabilities field contains bit sets that indicate whether a particular feature is implemented by
     this volume format.

     The following bits are defined in the first element (indexed by VOL_CAPABILITIES_FORMAT) of the
     capabilities and valid fields of the vol_capabilities_attr_t structure.

     VOL_CAP_FMT_PERSISTENTOBJECTIDS  If this bit is set the volume format supports persistent object iden-tifiers identifiers
                                      tifiers and can look up file system objects by their IDs.  See
                                      ATTR_CMN_OBJPERMANENTID for details about how to obtain these identi-fiers. identifiers.
                                      fiers.

     VOL_CAP_FMT_SYMBOLICLINKS        If this bit is set the volume format supports symbolic links.

     VOL_CAP_FMT_HARDLINKS            If this bit is set the volume format supports hard links.

     VOL_CAP_FMT_JOURNAL              If this bit is set the volume format supports a journal used to speed
                                      recovery in case of unplanned restart (such as a power outage or
                                      crash).  This does not necessarily mean the volume is actively using a
                                      journal.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_JOURNAL_ACTIVE       If this bit is set the volume is currently using a journal for speedy
                                      recovery after an unplanned restart.  This bit can be set only if
                                      VOL_CAP_FMT_JOURNAL is also set.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_NO_ROOT_TIMES        If this bit is set the volume format does not store reliable times for
                                      the root directory, so you should not depend on them to detect
                                      changes, identify volumes across unmount/mount, and so on.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_SPARSE_FILES         If this bit is set the volume format supports sparse files, that is,
                                      files which can have 'holes' that have never been written to, and thus
                                      do not consume space on disk.  A sparse file may have an allocated
                                      size on disk that is less than its logical length (that is,
                                      ATTR_FILE_ALLOCSIZE < ATTR_FILE_TOTALSIZE ).

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_ZERO_RUNS            For security reasons, parts of a file (runs) that have never been
                                      written to must appear to contain zeroes.  When this bit is set, the
                                      volume keeps track of allocated but unwritten runs of a file so that
                                      it can substitute zeroes without actually writing zeroes to the media.
                                      This provides performance similar to sparse files, but not the space
                                      savings.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_CASE_SENSITIVE       If this bit is set the volume format treats upper and lower case char-
                                      acters in file and directory names as different.  Otherwise an upper
                                      case character is equivalent to a lower case character, and you can't
                                      have two names that differ solely in the case of the characters.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_CASE_PRESERVING      If this bit is set the volume format preserves the case of file and
                                      directory names.  Otherwise the volume may change the case of some
                                      characters (typically making them all upper or all lower case).  A
                                      volume that sets VOL_CAP_FMT_CASE_SENSITIVE must also set
                                      VOL_CAP_FMT_CASE_PRESERVING.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_FAST_STATFS          This bit is used as a hint to upper layers (specifically the Carbon
                                      File Manager) to indicate that statfs(2) is fast enough that its
                                      results need not be cached by the caller.  A volume format implementa-tion implementation
                                      tion that caches the statfs(2) information in memory should set this
                                      bit.  An implementation that must always read from disk or always per-form perform
                                      form a network transaction to satisfy statfs(2) should not set this
                                      bit.

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_FMT_2TB_FILESIZE         If this bit is set the volume format supports file sizes larger than
                                      4GB, and potentially up to 2TB; it does not indicate whether the file
                                      system supports files larger than that.

                                      Introduced with Darwin 8.0 (Mac OS X version 10.4).

     VOL_CAP_FMT_OPENDENYMODES        If this bit is set, the volume format supports open deny modes (e.g.,
                                      "open for read write, deny write").

     VOL_CAP_FMT_HIDDEN_FILES         If this bit is set, the volume format supports the UF_HIDDEN file
                                      flag, and the UF_HIDDEN flag is mapped to that volume's native "hid-den" "hidden"
                                      den" or "invisible" bit (e.g., the invisible bit from the Finder Info
                                      extended attribute).

     VOL_CAP_FMT_PATH_FROM_ID         If this bit is set, the volume format supports the ability to derive a
                                      pathname to the root of the file system given only the ID of an
                                      object.  This also implies that object IDs on this file system are
                                      persistent and not recycled.  Most file systems will not support this
                                      capability.

     VOL_CAP_FMT_NO_VOLUME_SIZES      If this bit is set the volume format does not support determining val-ues values
                                      ues for total data blocks, available blocks, or free blocks, as in
                                      f_blocks, f_bavail, and f_bfree in the struct statfs returned by
                                      statfs(2).  Historically, those values were set to 0xFFFFFFFF for vol-umes volumes
                                      umes that did not support them.

                                      Introduced with Darwin 10.0 (Mac OS X version 10.6).

     VOL_CAP_FMT_64BIT_OBJECT_IDS     If this bit is set, the volume format uses object IDs that are 64-bit.
                                      This means that ATTR_CMN_FILEID and ATTR_CMN_PARENTID are the only
                                      legitimate attributes for obtaining object IDs from this volume and
                                      the 32-bit fid_objno fields of the fsobj_id_t returned by
                                      ATTR_CMN_OBJID, ATTR_CMN_OBJPERMANENTID, and ATTR_CMN_PAROBJID are
                                      undefined.

     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 (pri-vate (private
                                      vate and undocumented) copyfile() function.  (This is not the
                                      copyfile(3) function.)

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_INT_ALLOCATE             If this bit is set the volume format implementation supports the
                                      F_PREALLOCATE selector of fcntl(2).

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_INT_VOL_RENAME           If this bit is set the volume format implementation allows you to mod-ify modify
                                      ify the volume name using setattrlist(2).

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_INT_ADVLOCK              If this bit is set the volume format implementation supports advisory
                                      locking, that is, the F_GETLK, F_SETLK, and F_SETLKW selectors to
                                      fcntl(2).

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_INT_FLOCK                If this bit is set the volume format implementation supports whole
                                      file locks.  This includes flock(2) and the O_EXLOCK and O_SHLOCK
                                      flags to open(2).

                                      Introduced with Darwin 7.0 (Mac OS X version 10.3).

     VOL_CAP_INT_EXTENDED_SECURITY    If this bit is set the volume format implementation supports extended
                                      security controls (ACLs).

                                      Introduced with Darwin 8.0 (Mac OS X version 10.4).

     VOL_CAP_INT_USERACCESS           If this bit is set the volume format implementation supports the
                                      ATTR_CMN_USERACCESS attribute.

                                      Introduced with Darwin 8.0 (Mac OS X version 10.4).

     VOL_CAP_INT_MANLOCK              If this bit is set, the volume format implementation supports AFP-style AFPstyle
                                      style mandatory byte range locks via ioctl(2).

     VOL_CAP_INT_EXTENDED_ATTR        If this bit is set, the volume format implementation supports native
                                      extended attributes (see setxattr(2) ).

     VOL_CAP_INT_NAMEDSTREAMS         If this bit is set, the volume format implementation supports native
                                      named streams.

     A volume can also report which attributes it supports.  This information is returned by the
     ATTR_VOL_ATTRIBUTES attribute, which returns a vol_attributes_attr_t structure (shown below).

     typedef struct attribute_set {
         attrgroup_t commonattr; /* common attribute group */
         attrgroup_t volattr;    /* volume attribute group */
         attrgroup_t dirattr;    /* directory attribute group */
         attrgroup_t fileattr;   /* file attribute group */
         attrgroup_t forkattr;   /* fork attribute group */
     } attribute_set_t;

     typedef struct vol_attributes_attr {
         attribute_set_t validattr;
         attribute_set_t nativeattr;
     } vol_attributes_attr_t;

     The validattr field consists of a number of bit sets that indicate whether an attribute is supported by
     the volume format implementation.  The nativeattr is similar except that the bit sets indicate whether
     an attribute is supported natively by the volume format.  An attribute is supported natively if the
     volume format implementation does not have to do any complex conversions to access the attribute.  For
     example, a volume format might support persistent object identifiers, but doing so requires a complex
     table lookup that is not part of the core volume format.  In that case, the ATTR_VOL_ATTRIBUTES
     attribute would return ATTR_CMN_OBJPERMANENTID set in the validattr field of the vol_attributes_attr_t,
     but not in the nativeattr field.

RETURN VALUES
     Upon successful completion a value of 0 is returned.  Otherwise, a value of -1 is returned and errno is
     set to indicate the error.

COMPATIBILITY
     Not all volumes support getattrlist().  The best way to test whether a volume supports this function is
     to simply call it and check the error result.  getattrlist() will return ENOTSUP if it is not supported
     on a particular volume.

     The getattrlist() function has been undocumented for more than two years.  In that time a number of
     volume format implementations have been created without a proper specification for the behaviour of
     this routine.  You may encounter volume format implementations with slightly different behaviour than
     what is described here.  Your program is expected to be tolerant of this variant behaviour.

     If you're implementing a volume format that supports getattrlist(), you should be careful to support
     the behaviour specified by this document.

ERRORS
     getattrlist() and fgetattrlist() will fail if:

     [ENOTSUP]          The volume does not support the query.

     [ENOTDIR]          A component of the path prefix for getattrlist() is not a directory.

     [ENAMETOOLONG]     A component of a path name for getattrlist() exceeded NAME_MAX characters, or an
                        entire path name exceeded PATH_MAX characters.

     [ENOENT]           The file system object for getattrlist() does not exist.

     [EBADF]            The file descriptor argument for fgetattrlist() is not a valid file descriptor.

     [EACCES]           Search permission is denied for a component of the path prefix for getattrlist().

     [ELOOP]            Too many symbolic links were encountered in translating the pathname for
                        getattrlist().

     [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 reference the root of the volume.

     [EROFS]            The volume is read-only but must be modified in order to return this attribute.

     [EIO]              An I/O error occurred while reading from or writing to the file system.

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 compatibility reasons.  When ordering
     attributes, you should always use the order in which they are described above.

     The timespec structure is 64-bits (two 32-bit elements) in 32-bit code, and 128-bits (two 64-bit ele-ments) elements)
     ments) in 64-bit code; however, it is aligned on a 4-byte (32-bit) boundary, even in 64-bit code.

     If you use a structure for the attribute data, it must be correctly packed and aligned (see examples).

     Inconsistent behavior may be observed when the ATTR_CMN_FULLPATH attribute is requested on hard-linked
     items, particularly when the file system does not support ATTR_CMN_PARENTID natively. Callers should be
     aware of this when requesting the full path of a hard-linked item, especially if the full path crosses
     mount points.

     For more caveats, see also the compatibility notes above.

EXAMPLES
     The following code prints the file type and creator of a file, assuming that the volume supports the
     required attributes.

     #include <assert.h>
     #include <stdio.h>
     #include <string.h>
     #include <sys/attr.h>
     #include <sys/errno.h>
     #include <unistd.h>
     #include <sys/vnode.h>

     typedef struct attrlist attrlist_t;

     struct FInfoAttrBuf {
         u_int32_t       length;
         fsobj_type_t    objType;
         char            finderInfo[32];
     }  __attribute__((aligned(4), packed));
     typedef struct FInfoAttrBuf FInfoAttrBuf;

     static int FInfoDemo(const char *path)
     {
         int             err;
         attrlist_t      attrList;
         FInfoAttrBuf    attrBuf;

         memset(&attrList, 0, sizeof(attrList));
         attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
         attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;

         err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
         if (err != 0) {
             err = errno;
         }

         if (err == 0) {
             assert(attrBuf.length == sizeof(attrBuf));

             printf("Finder information for %s:\n", path);
             switch (attrBuf.objType) {
                 case VREG:
                     printf("file type    = '%.4s'\n", &attrBuf.finderInfo[0]);
                     printf("file creator = '%.4s'\n", &attrBuf.finderInfo[4]);
                     break;
                 case VDIR:
                     printf("directory\n");
                     break;
                 default:
                     printf("other object type, %d\n", attrBuf.objType);
                     break;
             }
         }

         return err;
     }

     The following code is an alternative implementation that uses nested structures to group the related
     attributes.

     #include <assert.h>
     #include <stdio.h>
     #include <stddef.h>
     #include <string.h>
     #include <sys/attr.h>
     #include <sys/errno.h>
     #include <unistd.h>
     #include <sys/vnode.h>

     typedef struct attrlist attrlist_t;

     struct FInfo2CommonAttrBuf {
         fsobj_type_t    objType;
         char            finderInfo[32];
     } __attribute__((aligned(4), packed));
     typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;

     struct FInfo2AttrBuf {
         u_int32_t           length;
         FInfo2CommonAttrBuf common;
     } __attribute__((aligned(4), packed));;
     typedef struct FInfo2AttrBuf FInfo2AttrBuf;

     static int FInfo2Demo(const char *path)
     {
         int             err;
         attrlist_t      attrList;
         FInfo2AttrBuf   attrBuf;

         memset(&attrList, 0, sizeof(attrList));
         attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
         attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;

         err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
         if (err != 0) {
             err = errno;
         }

         if (err == 0) {
             assert(attrBuf.length == sizeof(attrBuf));

             printf("Finder information for %s:\n", path);
             switch (attrBuf.common.objType) {
                 case VREG:
                     printf(
                         "file type    = '%.4s'\n",
                         &attrBuf.common.finderInfo[0]
                     );
                     printf(
                         "file creator = '%.4s'\n",
                         &attrBuf.common.finderInfo[4]
                     );
                     break;
                 case VDIR:
                     printf("directory\n");
                     break;
                 default:
                     printf(
                         "other object type, %d\n",
                         attrBuf.common.objType
                     );
                     break;
             }
         }

         return err;
     }

     The following example shows how to deal with variable length attributes.  It assumes that the volume
     specified by path supports the necessary attributes.

     #include <assert.h>
     #include <stdio.h>
     #include <stddef.h>
     #include <string.h>
     #include <sys/attr.h>
     #include <sys/errno.h>
     #include <unistd.h>
     #include <sys/vnode.h>

     typedef struct attrlist attrlist_t;

     struct VolAttrBuf {
         u_int32_t       length;
         u_int32_t       fileCount;
         u_int32_t       dirCount;
         attrreference_t mountPointRef;
         attrreference_t volNameRef;
         char            mountPointSpace[MAXPATHLEN];
         char            volNameSpace[MAXPATHLEN];
     } __attribute__((aligned(4), packed));
     typedef struct VolAttrBuf VolAttrBuf;

     static int VolDemo(const char *path)
     {
         int             err;
         attrlist_t      attrList;
         VolAttrBuf      attrBuf;

         memset(&attrList, 0, sizeof(attrList));
         attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
         attrList.volattr     =   ATTR_VOL_INFO
                                | ATTR_VOL_FILECOUNT
                                | ATTR_VOL_DIRCOUNT
                                | ATTR_VOL_MOUNTPOINT
                                | ATTR_VOL_NAME;

         err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
         if (err != 0) {
             err = errno;
         }

         if (err == 0) {
             assert(attrBuf.length >  offsetof(VolAttrBuf, mountPointSpace));
             assert(attrBuf.length <= sizeof(attrBuf));

             printf("Volume information for %s:\n", path);
             printf("ATTR_VOL_FILECOUNT:  %u\n", attrBuf.fileCount);
             printf("ATTR_VOL_DIRCOUNT:   %u\n", attrBuf.dirCount);
             printf(
                 "ATTR_VOL_MOUNTPOINT: %.*s\n",
                 (int) attrBuf.mountPointRef.attr_length,
                 ( ((char *) &attrBuf.mountPointRef)
                   + attrBuf.mountPointRef.attr_dataoffset )
             );
             printf(
                 "ATTR_VOL_NAME:       %.*s\n",
                 (int) attrBuf.volNameRef.attr_length,
                 ( ((char *) &attrBuf.volNameRef)
                   + attrBuf.volNameRef.attr_dataoffset )
             );
         }

         return err;
     }

     The following sample demonstrates the need to use packing and alignment controls; without the
     attribute, in 64-bit code, the fields of the structure are not placed at the locations that the kernel
     expects.

     #include <stdio.h>
     #include <stdlib.h>
     #include <unistd.h>
     #include <string.h>
     #include <err.h>
     #include <time.h>
     #include <sys/attr.h>

     /* The alignment and packing attribute is necessary in 64-bit code */
     struct AttrListTimes {
             u_int32_t       length;
             struct timespec st_crtime;
             struct timespec st_modtime;
     } __attribute__((aligned(4), packed));

     main(int argc, char **argv)
     {
             int             rv;
             int             i;

             for (i = 1; i < argc; i++) {
                     struct attrlist attrList;
                     struct AttrListTimes myStat = {0};
                     char           *path = argv[i];

                     memset(&attrList, 0, sizeof(attrList));
                     attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
                     attrList.commonattr = ATTR_CMN_CRTIME |
                             ATTR_CMN_MODTIME;

                     rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);

                     if (rv == -1) {
                             warn("getattrlist(%s)", path);
                             continue;
                     }
                     printf("%s:  Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
             }
             return 0;
     }

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

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback