xnu-4570.1.46.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 124e695c9726c28c320fdac2cd3be10fc8d3e0d9..a92c08dcd5a345883174cb6b5f5b16735a961fd6 100644 (file)
--- a/bsd/man/man2/getattrlist.2
+++ b/bsd/man/man2/getattrlist.2
@@ -182,6 +182,8 @@ 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.
 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.

+If the FSOPT_ATTR_CMN_EXTENDED option is given, this bit set is reinterpreted
+as extended common attributes attributes, also described below.

 .
 .El
 .Pp
 .
 .El
 .Pp


@@ -240,8 +242,8 @@ If this is bit is set, then
 .Dv ATTR_CMN_GEN_COUNT
 and
 .Dv ATTR_CMN_DOCUMENT_ID
 .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.
+can be requested. When this option is used, forkattrs are reinterpreted as a
+set of extended common attributes.

 .
 .El
 .
 .
 .El
 .


@@ -439,6 +441,13 @@ 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
 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

+.Pp
+ATTR_CMN_OBJID is deprecated sarting with macOS 10.13, iOS 11.0, watchOS 4.0 and
+tvOS 11.0 and ATTR_CMNEXT_LINKID should be used in its place.
+ATTR_CMN_OBJID can only be used on older operating systems only if the file
+system doesn't 64 bit IDs. See the
+.Fn getLinkIDInfo
+function in the EXAMPLES section.

 .
 .It ATTR_CMN_OBJPERMANENTID
 An
 .
 .It ATTR_CMN_OBJPERMANENTID
 An


@@ -499,7 +508,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.


@@ -669,7 +678,7 @@ 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 it's mounted volume. 
+that uniquely identifies the file system object within its mounted volume.

 Equivalent to 
 .Fa st_ino
 field of the
 Equivalent to 
 .Fa st_ino
 field of the


@@ -897,6 +906,16 @@ A
 containing the file system UUID.  Typically this will be a
 version 5 UUID.
 .
 containing the file system UUID.  Typically this will be a
 version 5 UUID.
 .

+.It ATTR_VOL_QUOTA_SIZE
+An
+.Vt off_t
+containing the maximum size of the volume in bytes.
+.
+.It ATTR_VOL_RESERVED_SIZE
+An
+.Vt off_t
+containing the minimum size of the volume in bytes.
+.

 .It ATTR_VOL_ATTRIBUTES
 A
 .Vt vol_attributes_attr_t
 .It ATTR_VOL_ATTRIBUTES
 A
 .Vt vol_attributes_attr_t


@@ -934,6 +953,21 @@ Currently the only flag defined is
 .Dv DIR_MNTSTATUS_MNTPOINT,
 which indicates that there is a file system mounted on this directory.
 .
 .Dv DIR_MNTSTATUS_MNTPOINT,
 which indicates that there is a file system mounted on this directory.
 .

+.It ATTR_DIR_ALLOCSIZE
+An
+.Vt off_t
+containing the number of bytes on disk used by the directory
+(the physical size).
+.
+.It ATTR_DIR_IOBLOCKSIZE
+A
+.Vt u_int32_t
+containing the optimal block size when reading or writing data.
+.
+.It ATTR_DIR_DATALENGTH
+An
+.Vt off_t
+containing the length of the directory in bytes (the logical size).

 .El
 .
 .Pp
 .El
 .
 .Pp


@@ -1077,28 +1111,78 @@ are directories.
 .
 Fork attributes relate to the actual data in the file,
 which can be held in multiple named contiguous ranges, or forks.
 .
 Fork attributes relate to the actual data in the file,
 which can be held in multiple named contiguous ranges, or forks.

+These cannot be used if the FSOPT_ATTR_CMN_EXTENDED is given.

 The following fork attributes are defined.
 .
 .Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
 .
 .It ATTR_FORK_TOTALSIZE
 The following fork attributes are defined.
 .
 .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.
 .

+.Sh COMMON EXTENDED ATTRIBUTES
+.
+Common extended attributes are like common attributes except that they are set
+in the forkattr field and can only be used if the FSOPT_ATTR_CMN_EXTENDED
+option is given. Use of these attributes is mutually exclusive with the above
+fork attributes.
+.
+.Bl -tag -width ATTR_VOL_ALLOCATIONCLUMP
+.
+.It ATTR_CMNEXT_RELPATH
+An
+.Vt attrreference
+structure containing the mount-relative path of
+the file system object as
+a UTF-8 encoded, null terminated C string.
+The attribute data length will not be greater than
+.Dv PATH_MAX.
+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
+relative path of a hard-linked item.
+.
+.It ATTR_CMNEXT_PRIVATESIZE
+An
+.Vt off_t
+containing the number of bytes that are \fBnot\fP trapped inside a clone
+or snapshot, and which would be freed immediately if the file were deleted.
+.
+.It ATTR_CMNEXT_LINKID
+A
+.Vt u_int64_t
+that uniquely identifies the file system object within a mounted volume for the
+duration of its mount.
+.Pp
+On HFS+ and APFS volumes, the ATTR_CMNEXT_LINKID of a file system
+object is distinct from the ATTR_CMNEXT_LINKID of any hard link to that file
+system object. Although the ATTR_CMNEXT_LINKID of a file system object may appear
+similar (in whole or in part) to its ATTR_CMN_FILEID (see description of
+ATTR_CMN_FILEID above), \fBno relation between the two attributes should ever be implied.\fP
+.
+.El
+.

 .Sh VOLUME CAPABILITIES
 .
 .\" vol_capabilities_attr_t
 .Sh VOLUME CAPABILITIES
 .
 .\" vol_capabilities_attr_t


@@ -1327,10 +1411,19 @@ 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. 
 .
 .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 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.
+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.
+.
+.It VOL_CAP_FMT_NO_IMMUTABLE_FILES
+If this bit is set, the volume format does not support setting the UF_IMMUTABLE
+flag.
+See ATTR_CMN_FLAGS for more details.
+.It VOL_CAP_FMT_NO_PERMISSIONS
+If this bit is set, the volume format does not support setting file
+permissions.
+See ATTR_CMN_USERACCESS for more details.

 .
 .El
 .Pp
 .
 .El
 .Pp


@@ -1440,12 +1533,36 @@ 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_CLONE
+If this bit is set, the file system supports cloning files and directories.
+See 
+.Xr clonefileat 2 
+for more details.
+.
+.It VOL_CAP_INT_SNAPSHOT
+If this bit is set, the file system supports snapshots.
+See
+.Xr fs_snapshot_create 2
+for more details.

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


@@ -1952,6 +2069,56 @@ main(int argc, char **argv)
        return 0;
 }
 .Ed
        return 0;
 }
 .Ed

+.Pp
+ The getLinkIDInfo() function determines if ATTR_CMNEXT_LINKID and ATTR_CMN_OBJID
+ are valid to use on the file system specified by path.
+.
+.Bd -literal
+int getLinkIDInfo(const char *path, bool *cmnExtLinkIDValid, bool *cmnObjIDValid)
+{
+    int result;
+    struct statfs statfsBuf;
+    struct attrlist attrList;
+    struct volAttrsBuf {
+        u_int32_t length;
+        vol_capabilities_attr_t capabilities;
+        vol_attributes_attr_t attributes;
+    } __attribute__((aligned(4), packed));
+    struct volAttrsBuf volAttrs;
+.Pp
+    memset(&attrList, 0, sizeof(attrList));
+    attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
+    attrList.volattr = ATTR_VOL_INFO | ATTR_VOL_CAPABILITIES | ATTR_VOL_ATTRIBUTES;
+    // get the file system's mount point path for the input path
+    result = statfs(path, &statfsBuf);
+    if ( result == 0 ) {
+        // get the supported capabilities and attributes
+        result = getattrlist(statfsBuf.f_mntonname, &attrList, &volAttrs, sizeof(volAttrs), FSOPT_ATTR_CMN_EXTENDED);
+        if ( result == 0 ) {
+            if ( volAttrs.attributes.validattr.forkattr & ATTR_CMNEXT_LINKID ) {
+                // ATTR_CMNEXT_LINKID is available; do not use ATTR_CMN_OBJID
+                *cmnExtLinkIDValid = true;
+                *cmnObjIDValid = false;
+            }
+            else {
+                // ATTR_CMNEXT_LINKID is not available
+                cmnExtLinkIDValid = false;
+                // ATTR_CMN_OBJID can only be used if the file system does not use 64-bit object IDs
+                if ( (volAttrs.capabilities.capabilities[VOL_CAPABILITIES_FORMAT] & VOL_CAP_FMT_64BIT_OBJECT_IDS) && (volAttrs.capabilities.valid[VOL_CAPABILITIES_FORMAT] & VOL_CAP_FMT_64BIT_OBJECT_IDS) ) {
+                    *cmnObjIDValid = false;
+                }
+                else {
+                    *cmnObjIDValid = true;
+                }
+            }
+        }
+    }
+    if ( result != 0 ) {
+        *cmnExtLinkIDValid = *cmnObjIDValid = false;
+    }
+    return result;
+}
+.Ed

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