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
.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
.
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
.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.
.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
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
.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
.
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
+Deprecated.
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).
.
+.It ATTR_FORK_RESERVED
+Reserved.
+You must set this to 0.
+.
.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.
.
+.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
.
.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
.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_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
.
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
projects / apple / xnu.git / blobdiff