xnu-3789.41.3.tar.gz

[apple/xnu.git] / bsd / man / man2 / getattrlist.2

diff --git a/bsd/man/man2/getattrlist.2 b/bsd/man/man2/getattrlist.2
index 856f1a11008d773fdf97bf09f15b031ba0f469a4..9f24d9c304e938e9040fe16d825f02ab3dbaec4c 100644 (file)
--- a/bsd/man/man2/getattrlist.2
+++ b/bsd/man/man2/getattrlist.2
@@ -16,12 +16,13 @@
 .\"
 .\"     @(#)getattrlist.2
 .
 .\"
 .\"     @(#)getattrlist.2
 .

-.Dd October 14, 2004
+.Dd February 25, 2014

 .Dt GETATTRLIST 2
 .Os Darwin
 .Sh NAME
 .Nm getattrlist ,
 .Dt GETATTRLIST 2
 .Os Darwin
 .Sh NAME
 .Nm getattrlist ,

-.Nm fgetattrlist
+.Nm fgetattrlist ,
+.Nm getattrlistat

 .Nd get file system attributes
 .Sh SYNOPSIS
 .Fd #include <sys/attr.h>
 .Nd get file system attributes
 .Sh SYNOPSIS
 .Fd #include <sys/attr.h>


@@ -31,6 +32,11 @@
 .
 .Ft int
 .Fn fgetattrlist "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
 .
 .Ft int
 .Fn fgetattrlist "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"

+.Ft int
+.Fo getattrlistat
+.Fa "int fd" "const char *path" "struct attrlist * attrList" "void * attrBuf"
+.Fa "size_t attrBufSize" "unsigned long options"
+.Fc

 .Sh DESCRIPTION
 The
 .Fn getattrlist
 .Sh DESCRIPTION
 The
 .Fn getattrlist


@@ -42,6 +48,28 @@ while
 .Fn fgetattrlist
 works on the provided file descriptor
 .Fa fd .
 .Fn fgetattrlist
 works on the provided file descriptor
 .Fa fd .

+.Pp
+The
+.Fn getattrlistat
+system call is equivalent to
+.Fn getattrlist
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the attributes are returned for the file system object named by
+path relative to the directory associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+If
+.Fn getattrlistat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is
+identical to a call to
+.Fn getattrlist .
+.Pp

 You can think of
 .Fn getattrlist
 as a seriously enhanced version of
 You can think of
 .Fn getattrlist
 as a seriously enhanced version of


@@ -59,18 +87,6 @@ The
 parameter lets you control specific aspects of the function's behavior.
 .Pp
 .
 parameter lets you control specific aspects of the function's behavior.
 .Pp
 .

-The
-.Fn getattrlist
-and
-.Fn fgetattrlist
-functions are 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
-the calls.
-.Pp
-.

 Not all volumes support all attributes.
 See the discussion of
 .Dv ATTR_VOL_ATTRIBUTES
 Not all volumes support all attributes.
 See the discussion of
 .Dv ATTR_VOL_ATTRIBUTES


@@ -219,6 +235,14 @@ will be used for the invalid ones.  Requires that
 .Dv ATTR_CMN_RETURNED_ATTRS
 be requested.
 .
 .Dv ATTR_CMN_RETURNED_ATTRS
 be requested.
 .

+.It FSOPT_ATTR_CMN_EXTENDED
+If this is bit is set, then
+.Dv ATTR_CMN_GEN_COUNT
+and
+.Dv ATTR_CMN_DOCUMENT_ID
+can be requested. When this option is used, callers must not reference
+forkattrs anywhere.
+.

 .El
 .
 .Sh ATTRIBUTE BUFFER
 .El
 .
 .Sh ATTRIBUTE BUFFER


@@ -343,10 +367,10 @@ 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
 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
-.Xr getattrlist 2 supports this attribute (
-.Xr getdirentriesattr 2 and
-.Xr searchfs 2 do not support it ).
+can be over-ridden using the FSOPT_PACK_INVAL_ATTRS option flag. Both
+.Xr getattrlist 2 and
+.Xr getatttrlistbulk 2 support this attribute while
+.Xr searchfs 2 does not.

 .
 .It ATTR_CMN_NAME
 An
 .
 .It ATTR_CMN_NAME
 An


@@ -354,8 +378,11 @@ An
 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
 structure containing the name of the file system object as
 UTF-8 encoded, null terminated C string.
 The attribute data length will not be greater than

-.Dv NAME_MAX +
-1.
+.Dv NAME_MAX
++ 1 characters, which is
+.Dv NAME_MAX
+* 3 + 1 bytes (as one UTF-8-encoded character may
+take up to three bytes).

 .Pp
 .
 .It ATTR_CMN_DEVID
 .Pp
 .
 .It ATTR_CMN_DEVID


@@ -382,15 +409,6 @@ field of the
 structure returned by
 .Xr statfs 2 .
 .
 structure returned by
 .Xr statfs 2 .
 .

-.Pp
-This value is not related to the file system ID from traditional Mac OS (for example,
-the
-.Fa filesystemID
-field of the
-.Vt FSVolumeInfo
-structure returned by Carbon's FSGetVolumeInfo() function).
-On current versions of Mac OS X that value is synthesised by the Carbon File Manager.
-.

 .It ATTR_CMN_OBJTYPE
 An
 .Vt fsobj_type_t
 .It ATTR_CMN_OBJTYPE
 An
 .Vt fsobj_type_t


@@ -412,48 +430,51 @@ in
 .It ATTR_CMN_OBJID
 An
 .Vt fsobj_id_t
 .It ATTR_CMN_OBJID
 An
 .Vt 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.
-.Pp
-.
-Some volume formats use well known values for the
-.Fa fid_objno
-field for the root directory (2) and the parent of root directory (1).
-This is not a required behaviour of this attribute.
+structure that uniquely identifies the file system object within a mounted 
+volume for the duration of it's mount; this identifier is not guaranteed to be 
+persistent for the volume and may change every time the volume is mounted.
+If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
+object identifier.
+.Pp
+On HFS+ volumes, the ATTR_CMN_OBJID of a file system object is distinct from 
+the ATTR_CMN_OBJID of any hard link to that file system object. Although the 
+ATTR_CMN_OBJID of a file system object may appear similar (in whole
+or in part) to it's ATTR_CMN_FILEID (see description of ATTR_CMN_FILEID below), 
+\fBno relation between the two attributes should ever be implied.\fP

 .
 .It ATTR_CMN_OBJPERMANENTID
 An
 .Vt fsobj_id_t
 .
 .It ATTR_CMN_OBJPERMANENTID
 An
 .Vt 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.
-.Pp
-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
-.Dv EROFS .
+structure that uniquely and persistently identifies the file system object
+within its volume; persistence implies that this attribute is unaffected by
+mount/unmount operations on the volume.
+If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
+object identifier.
+.Pp
+Some file systems can not return this attribute when the volume is mounted
+read-only and will fail the request with error
+.Dv EROFS.
+.br
+(e.g. original HFS modifies on disk structures to generate persistent
+identifiers, and hence cannot do so if the volume is mounted read only.)

 .
 .It ATTR_CMN_PAROBJID
 An
 .Vt fsobj_id_t
 .
 .It ATTR_CMN_PAROBJID
 An
 .Vt 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 identifier need not be persistent across an unmount/mount sequence.
+structure that uniquely identifies the parent directory of the file system
+object within a mounted volume, for the duration of the volume mount; this 
+identifier is not guaranteed to be persistent for the volume and may change 
+every time the volume is mounted.
+If the VOL_CAP_FMT_64BIT_OBJECT_IDS capability is set, this is instead a 64-bit
+object identifier.

 .Pp
 .
 .Pp
 .

-On a volume that supports hard links, a multiply linked file has no unique parent.
-This attribute will return an unspecified parent.
-.Pp
+If a file system object is hard linked from multiple directories, the parent
+directory returned for this attribute is non deterministic; it can be any one
+of the parent directories of this object.

 .
 .

-For some volume formats this attribute is very expensive to calculate.
+For some volume formats the computing cost for this attribute is significant; 
+developers are advised to request this attribute sparingly.

 .
 .It ATTR_CMN_SCRIPT
 (read/write) A
 .
 .It ATTR_CMN_SCRIPT
 (read/write) A


@@ -462,11 +483,8 @@ 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 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
-.Aq Pa CarbonCore/TextCommon.h .

 File systems that do not have an appropriate text encoding value should return
 kTextEncodingMacUnicode.
 File systems that do not have an appropriate text encoding value should return
 kTextEncodingMacUnicode.

-See DTS Q&A 1173 "File Manager Text Encoding Hints".

 .
 .It ATTR_CMN_CRTIME
 (read/write) A
 .
 .It ATTR_CMN_CRTIME
 (read/write) A


@@ -487,7 +505,7 @@ structure returned by
 .Xr stat 2 .
 .
 .It ATTR_CMN_CHGTIME
 .Xr stat 2 .
 .
 .It ATTR_CMN_CHGTIME

-(read/write) A
+A

 .Vt timespec
 structure containing the time that the file system object's
 attributes were last modified.
 .Vt timespec
 structure containing the time that the file system object's
 attributes were last modified.


@@ -530,8 +548,6 @@ structure
 structure and an
 .Vt ExtendedFolderInfo
 structure).
 structure and an
 .Vt ExtendedFolderInfo
 structure).

-These structures are defined in
-.Aq Pa CarbonCore/Finder.h .

 .Pp
 This attribute is not byte swapped by the file system.
 The value of multibyte fields on disk is always big endian.
 .Pp
 This attribute is not byte swapped by the file system.
 The value of multibyte fields on disk is always big endian.


@@ -570,18 +586,11 @@ field of the
 .Vt stat
 structure returned by
 .Xr stat 2 .
 .Vt stat
 structure returned by
 .Xr stat 2 .

-.
-.It ATTR_CMN_NAMEDATTRCOUNT
-A
-.Vt u_int32_t
-containing the number of named attributes of the file system object.
-.
-.It ATTR_CMN_NAMEDATTRLIST
-An
-.Vt 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.
+Only the permission bits of
+.Fa st_mode
+are valid; other bits should be ignored,
+e.g., by masking with
+.Dv ~S_IFMT .

 .
 .It ATTR_CMN_FLAGS
 (read/write) A
 .
 .It ATTR_CMN_FLAGS
 (read/write) A


@@ -595,19 +604,38 @@ structure returned by
 .Xr stat 2 .
 For more information about these flags, see
 .Xr chflags 2 .
 .Xr stat 2 .
 For more information about these flags, see
 .Xr chflags 2 .

+.
+.It ATTR_CMN_GEN_COUNT
+A
+.Vt u_int32_t
+containing a non zero monotonically increasing generation
+count for this file system object. The generation count tracks
+the number of times the data in a file system object has been 
+modified. No meaning can be implied from its value. The
+value of the generation count for a file system object can 
+be compared against a previous value of the same file system
+object for equality; i.e. an unchanged generation 
+count indicates identical data. Requesting this attribute requires the
+FSOPT_ATTR_CMN_EXTENDED option flag.

 .Pp
 .
 .Pp
 .

-The order that attributes are placed into the attribute buffer
-almost invariably matches the order of the attribute mask bit values.
-The exception is
-.Dv ATTR_CMN_FLAGS .
-If its order was based on its bit position, it would be before
-the
-.Dv ATTR_CMN_NAMEDATTRCOUNT
-/
-.Dv ATTR_CMN_NAMEDATTRLIST
-pair, however,
-it is placed in the buffer after them.
+A generation count value of 0 is invalid and cannot be used to 
+determine data change.
+.Pp
+The generation count is invalid while a file is mmap'ed. An invalid 
+generation count value of 0 will be returned for mmap'ed files.
+.
+.It ATTR_CMN_DOCUMENT_ID
+A
+.Vt u_int32_t
+containing the document id. The document id is a value assigned
+by the kernel to a document (which can be a file or directory)
+and is used to track the data regardless of where it gets moved. 
+The document id survives safe saves; i.e it is sticky to the path it 
+was assigned to. Requesting this attribute requires the
+FSOPT_ATTR_CMN_EXTENDED option flag.
+.Pp
+A document id of 0 is invalid.

 .
 .It ATTR_CMN_USERACCESS
 A
 .
 .It ATTR_CMN_USERACCESS
 A


@@ -647,7 +675,13 @@ Analoguous to
 .It ATTR_CMN_FILEID
 A
 .Vt u_int64_t
 .It ATTR_CMN_FILEID
 A
 .Vt u_int64_t

-that uniquely identifies the file system object within its volume. 
+that uniquely identifies the file system object within it's mounted volume. 
+Equivalent to 
+.Fa st_ino
+field of the
+.Vt stat
+structure returned by
+.Xr stat 2 .

 .
 .It ATTR_CMN_PARENTID
 A
 .
 .It ATTR_CMN_PARENTID
 A


@@ -665,6 +699,18 @@ The attribute data length will not be greater than
 Inconsistent behavior may be observed when this attribute is requested on
 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
 natively. Callers should be aware of this when requesting the full path of a hard-linked item.
 Inconsistent behavior may be observed when this attribute is requested on
 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
 natively. Callers should be aware of this when requesting the full path of a hard-linked item.

+.
+.It ATTR_CMN_ADDEDTIME
+A
+.Vt timespec
+that contains the time that the file system object was created or renamed into
+its containing directory.  Note that inconsistent behavior may be observed
+when this attribute is requested on hard-linked items. 
+.
+.It ATTR_CMN_DATA_PROTECT_FLAGS
+A
+.Vt u_int32_t
+that contains the file or directory's data protection class.

 .Pp
 .
 .El
 .Pp
 .
 .El


@@ -702,9 +748,6 @@ A
 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.
 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
-.Aq Pa CarbonCore/Files.h
-for more details.

 .
 .It ATTR_VOL_SIZE
 An
 .
 .It ATTR_VOL_SIZE
 An


@@ -1045,19 +1088,26 @@ The following fork attributes are defined.
 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 .
 .It ATTR_FORK_TOTALSIZE
 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 .
 .It ATTR_FORK_TOTALSIZE

+Deprecated.

 An
 .Vt off_t
 containing the length of the fork in bytes (the logical size).
 .
 .It ATTR_FORK_ALLOCSIZE
 An
 .Vt off_t
 containing the length of the fork in bytes (the logical size).
 .
 .It ATTR_FORK_ALLOCSIZE

+Deprecated.

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

+.It ATTR_FORK_RESERVED
+Reserved.
+You must set this to 0.
+.

 .El
 .Pp
 .
 .El
 .Pp
 .

-Fork attributes are not properly implemented by any current Mac OS X
+Fork attributes are deprecated and all bits are reserved.
+They are not properly implemented by any current Mac OS X

 volume format implementation.
 We strongly recommend that client programs do not request fork attributes.
 If you are implementing a volume format, you should not support these attributes.
 volume format implementation.
 We strongly recommend that client programs do not request fork attributes.
 If you are implementing a volume format, you should not support these attributes.


@@ -1233,7 +1283,7 @@ must also set
 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 .
 .It VOL_CAP_FMT_FAST_STATFS
 Introduced with Darwin 7.0 (Mac OS X version 10.3).
 .
 .It VOL_CAP_FMT_FAST_STATFS

-This bit is used as a hint to upper layers (specifically the Carbon File Manager) to
+This bit is used as a hint to upper layers to

 indicate that
 .Xr statfs 2
 is fast enough that its results need not be cached by the caller.
 indicate that
 .Xr statfs 2
 is fast enough that its results need not be cached by the caller.


@@ -1288,6 +1338,13 @@ that did not support them.
 .Pp
 Introduced with Darwin 10.0 (Mac OS X version 10.6).
 .
 .Pp
 Introduced with Darwin 10.0 (Mac OS X version 10.6).
 .

+.It VOL_CAP_FMT_64BIT_OBJECT_IDS
+If this bit is set, the volume format uses object IDs that are 64-bit. 
+This means that ATTR_CMN_FILEID and ATTR_CMN_PARENTID are the primary means of
+obtaining object IDs from this volume. The values returned by ATTR_CMN_OBJID,
+ATTR_CMN_OBJPERMANENTID, and ATTR_CMN_PAROBJID can be interpreted as 64-bit
+object IDs instead of fsobj_id_t.
+.

 .El
 .Pp
 .
 .El
 .Pp
 .


@@ -1396,12 +1453,24 @@ AFP-style mandatory byte range locks via
 .It VOL_CAP_INT_EXTENDED_ATTR
 If this bit is set, the volume format implementation supports
 native extended attributes (see
 .It VOL_CAP_INT_EXTENDED_ATTR
 If this bit is set, the volume format implementation supports
 native extended attributes (see

-.Xr setxattr 2 ).
+.Xr setxattr 2 Ns ).

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

+.It VOL_CAP_INT_RENAME_SWAP
+If this bit is set, the file system supports swapping file system
+objects.  See
+.Xr rename 2
+for more details.
+.
+.It VOL_CAP_INT_RENAME_EXCL
+If this bit is set, the file system supports an exclusive rename
+operation. See
+.Xr rename 2
+for more details.
+.

 .El
 .Pp
 .
 .El
 .Pp
 .


@@ -1566,6 +1635,30 @@ The volume is read-only but must be modified in order to return this attribute.
 An I/O error occurred while reading from or writing to the file system.
 .El
 .Pp
 An I/O error occurred while reading from or writing to the file system.
 .El
 .Pp

+In addition to the errors returned by the
+.Fn getattrlist ,
+the
+.Fn getattrlistat
+function may fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
+.El
+.Pp

 .
 .Sh CAVEATS
 .
 .
 .Sh CAVEATS
 .


@@ -1583,15 +1676,6 @@ For example,
 (0x00000001) comes before
 .Dv ATTR_CMN_DEVID
 (0x00000002) because its value is smaller.
 (0x00000001) comes before
 .Dv ATTR_CMN_DEVID
 (0x00000002) because its value is smaller.

-However, you can not rely on this ordering because there is one key exception:
-.Dv ATTR_CMN_FLAGS
-is placed after the
-.Dv ATTR_CMN_NAMEDATTRCOUNT
-/
-.Dv 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.
 .Pp
 When ordering attributes, you should always use the order in which they
 are described above.
 .Pp


@@ -1602,6 +1686,10 @@ structure is 64-bits (two 32-bit elements) in 32-bit code, and
 128-bits (two 64-bit elements) in 64-bit code; however, it is aligned
 on a 4-byte (32-bit) boundary, even in 64-bit code.
 .Pp
 128-bits (two 64-bit elements) in 64-bit code; however, it is aligned
 on a 4-byte (32-bit) boundary, even in 64-bit code.
 .Pp

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

 .
 Inconsistent behavior may be observed when the ATTR_CMN_FULLPATH attribute is requested on
 hard-linked items, particularly when the file system does not support ATTR_CMN_PARENTID
 .
 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


@@ -1633,7 +1721,7 @@ struct FInfoAttrBuf {
     u_int32_t       length;
     fsobj_type_t    objType;
     char            finderInfo[32];
     u_int32_t       length;
     fsobj_type_t    objType;
     char            finderInfo[32];

-};
+}  __attribute__((aligned(4), packed));

 typedef struct FInfoAttrBuf FInfoAttrBuf;
 .Pp
 .
 typedef struct FInfoAttrBuf FInfoAttrBuf;
 .Pp
 .


@@ -1700,14 +1788,14 @@ typedef struct attrlist attrlist_t;
 struct FInfo2CommonAttrBuf {
     fsobj_type_t    objType;
     char            finderInfo[32];
 struct FInfo2CommonAttrBuf {
     fsobj_type_t    objType;
     char            finderInfo[32];

-};
+} __attribute__((aligned(4), packed));

 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
 .Pp
 .
 struct FInfo2AttrBuf {
     u_int32_t           length;
     FInfo2CommonAttrBuf common;
 typedef struct FInfo2CommonAttrBuf FInfo2CommonAttrBuf;
 .Pp
 .
 struct FInfo2AttrBuf {
     u_int32_t           length;
     FInfo2CommonAttrBuf common;

-};
+} __attribute__((aligned(4), packed));;

 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
 .Pp
 .
 typedef struct FInfo2AttrBuf FInfo2AttrBuf;
 .Pp
 .


@@ -1790,7 +1878,7 @@ struct VolAttrBuf {
     attrreference_t volNameRef;
     char            mountPointSpace[MAXPATHLEN];
     char            volNameSpace[MAXPATHLEN];
     attrreference_t volNameRef;
     char            mountPointSpace[MAXPATHLEN];
     char            volNameSpace[MAXPATHLEN];

-};
+} __attribute__((aligned(4), packed));

 typedef struct VolAttrBuf VolAttrBuf;
 .Pp
 .
 typedef struct VolAttrBuf VolAttrBuf;
 .Pp
 .


@@ -1843,6 +1931,53 @@ static int VolDemo(const char *path)
 }
 .Ed
 .Pp
 }
 .Ed
 .Pp

+The following sample demonstrates the need to use packing and alignment
+controls; without the attribute, in 64-bit code, the fields of the structure are not
+placed at the locations that the kernel expects.
+.
+.Bd -literal
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <err.h>
+#include <time.h>
+#include <sys/attr.h>
+.Pp
+/* The alignment and packing attribute is necessary in 64-bit code */
+struct AttrListTimes {
+       u_int32_t       length;
+       struct timespec st_crtime;
+       struct timespec st_modtime;
+} __attribute__((aligned(4), packed));
+.Pp
+main(int argc, char **argv)
+{
+       int             rv;
+       int             i;
+.Pp
+       for (i = 1; i < argc; i++) {
+               struct attrlist attrList;
+               struct AttrListTimes myStat = {0};
+               char           *path = argv[i];
+.Pp
+               memset(&attrList, 0, sizeof(attrList));
+               attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
+               attrList.commonattr = ATTR_CMN_CRTIME |
+                       ATTR_CMN_MODTIME;
+.Pp
+               rv = getattrlist(path, &attrList, &myStat, sizeof(myStat), 0);
+.Pp
+               if (rv == -1) {
+                       warn("getattrlist(%s)", path);
+                       continue;
+               }
+               printf("%s:  Modification time = %s", argv[i], ctime(&myStat.st_modtime.tv_sec));
+       }
+       return 0;
+}
+.Ed
+.Pp

 .
 .Sh SEE ALSO
 .
 .
 .Sh SEE ALSO
 .


@@ -1850,7 +1985,7 @@ static int VolDemo(const char *path)
 .Xr chflags 2 ,
 .Xr exchangedata 2 ,
 .Xr fcntl 2 ,
 .Xr chflags 2 ,
 .Xr exchangedata 2 ,
 .Xr fcntl 2 ,

-.Xr getdirentriesattr 2 ,
+.Xr getattrlistbulk 2 ,

 .Xr mount 2 ,
 .Xr searchfs 2 ,
 .Xr setattrlist 2 ,
 .Xr mount 2 ,
 .Xr searchfs 2 ,
 .Xr setattrlist 2 ,


@@ -1861,4 +1996,6 @@ static int VolDemo(const char *path)
 A
 .Fn getattrlist
 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
 A
 .Fn getattrlist
 function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).

-.
+The
+.Fn getattrlistat
+function call appeared in OS X 10.10 .