Because iCloud Drive presents the illusion of a file system similar to APFS on your Mac, it’s easy to assume that it behaves the same. In some respects, though, it’s very different from the local file systems your Mac uses. In this article, I look at how iCloud Drive handles extended attributes, responsible for storing metadata for many purposes.

In the past, extended attributes (xattrs) have been poorly preserved during file transfer operations. As they have grown in importance and use, that has been addressed. While some are designated as ephemeral and intended to be removed in many situations, defaults should now preserve significant xattrs well.

When you transfer files between Macs using AirDrop or in Zip archives created by Archive Utility, the general rule is for all xattrs to be preserved unless they’re specially tagged for removal. The major exception to that is the quarantine xattr, com.apple.quarantine, which is either added or refreshed (if it’s already present) when transferring by AirDrop, even inside a Zip archive. In the latter case, unzipping the archive after transfer by AirDrop normally propagates quarantine xattrs to each file as it’s unzipped.

Testing

To assess how well xattrs are preserved in iCloud Drive, I assembled a folder of 28 test files with a total of 152 xattrs attached to them, covering 37 different types intended for preservation. Some were deliberately constructed as test cases, including three com.apple.ResourceFork, one of which contained a thumbnail image, a com.apple.metadata:kMDLabel_[…] containing nearly 180 KB of text, and an arbitrary type of co.eclecticlight.test3 of 80 KB. Although most types were standard com.apple.[…] xattrs, tests included types used by Skim, org.openmetainfo.[…], and my own co.eclecticlight.dintch.hash and co.eclecticlight.dintch.time used for integrity checking.

Local iCloud Drive access

Moving the test folder from ~/Documents to that Home folder’s iCloud Drive apparently preserved all xattrs without any removals or changes at all. However, following eviction and download to the same Mac, three xattr types were removed:

• co.eclecticlight.test3 (length 80059 bytes)
• com.apple.ResourceFork (all three samples)
• com.apple.metadata:kMDLabel_[…] (length 179750 bytes).

When the files had been evicted and were represented by stub files, each had a com.apple.icloud.itemName xattr attached, containing its original file name. Also added were empty com.apple.metadata:_kMDItemUserTags xattrs. When those files were downloaded again, the com.apple.icloud.itemName xattrs were removed, but the com.apple.metadata:_kMDItemUserTags xattrs remained.

Remote iCloud Drive access

Accessing the test folder from a second Mac produced a very different result. Xattrs that were retained included:

• com.apple.TextEncoding
• com.apple.lastuseddate#PS
• com.apple.metadata:kMDItem[…] types
• com.apple.metadata:kMDLabel_[…] when small in size
• com.apple.quarantine
• co.eclecticlight.dintch.hash#S
• co.eclecticlight.dintch.time#S

All other third-party xattrs were stripped, as were all com.apple.ResourceFork, com.apple.macl, and the one com.apple.metadata:kMDLabel_[…] of nearly 180 KB size.

Explanation

The illusion that all xattrs are retained by iCloud Drive when read from the same Mac that uploaded them isn’t the result of those xattrs being stored alongside the file’s data in iCloud Drive. Instead, those xattrs are accessed from the local file system. Eviction thus appears to change local metadata by deleting large xattrs, and all com.apple.ResourceFork xattrs.

Loss of those larger xattrs may result from the fact that APFS can only store a maximum of 3804 bytes of data within a xattr file system object. Larger xattrs require a separate xattr data stream. Whether those are being deliberately removed on eviction, or this behaviour is a bug, isn’t clear as this isn’t documented. However, removal of all Resource Forks is independent of their size, and appears to be intentional.

Retention of xattrs in iCloud Drive broadly follows the pattern already established, although like everything else here it appears to be undocumented for users or developers. This is based on a system of xattr flags and defaults to determine the persistence of each type of xattr in actions such as copying. These are detailed in the appendix.

The end result can be puzzling discrepancies for the user and developer. For example, although I’m sure they have long since been deprecated, Resource Forks can still be used to provide a custom thumbnail that’s displayed in preference to the default set by QuickLook. As that is accessed from the local file system on a Mac that uploaded the file to iCloud Drive, on that Mac the custom thumbnail will be displayed until the file is evicted; when it’s downloaded again, the Resource Fork will have been stripped, and the custom thumbnail has vanished. But on a different Mac accessing the same file in iCloud Drive, the custom thumbnail won’t have been shown at all.

Although that might seem an edge case, vanishing metadata can have other significant impacts on apps that rely on it.

Summary

• On the Mac that uploads files with xattrs, iCloud Drive appears to preserve almost all xattrs because they’re accessed from the local file system, not iCloud Drive.
• Larger xattrs and all Resource Forks are stripped by the eviction-download cycle.
• Other Macs accessing the same files in iCloud Drive are provided a more limited range of xattr types which excludes all third-party types unless they’re specially tagged for retention.
• None of this is documented for users or developers, except in source code files.

Appendix: xattr flags

In 2013, as part of its enhancements for iCloud in particular, Apple added support for flags on xattrs to indicate how those xattrs should be treated when the file is copied in various ways. Rather than change the file system, Apple opted for an elegant kludge: appending characters to the end of the xattr’s name.

If you work with xattrs, you’ve probably already seen this in xattrs like com.apple.lastuseddate#PS whose name ends with a hash # then one or more characters: those are actually the flags, not part of the name, what Apple refers to as a ‘property list’. To avoid confusion I won’t use that term here, but refer to them as xattr flags.

Flags can be upper or lower case letters C, N, P and S, and invariably follow the # separator, which is presumably otherwise forbidden from use in a xattr’s name. Upper case sets (enables) that property, while lower case clears (disables) that property. The properties are:

• C: XATTR_FLAG_CONTENT_DEPENDENT, which ties the flag and the file contents, so the xattr is rewritten when the file data changes. This is normally used for checksums and hashes, text encoding, and position information. The xattr is preserved for copy and share, but not in a safe save.
• P: XATTR_FLAG_NO_EXPORT, which doesn’t export the xattr, but normally preserves it during copying.
• N: XATTR_FLAG_NEVER_PRESERVE, which ensures the xattr is never copied, even when copying the file.
• S: XATTR_FLAG_SYNCABLE, which ensures the xattr is preserved even during syncing. Default behaviour is for xattrs to be stripped during syncing, to minimise the amount of data to be transferred, but this will override that default.

These must operate within another general restriction of xattrs: their name cannot exceed a maximum of 127 UTF-8 characters.

Defaults are baked into the xattr flag code, where as of 2013 the following default flags are set for different types of xattr (* here represents the wild card):

• com.apple.quarantine – PCS
• com.apple.TextEncoding – CS
• com.apple.metadata:* – PS
• com.apple.security.* – S
• com.apple.ResourceFork – PCS
• com.apple.FinderInfo – PCS

Some default flags may have changed since 2013, or the C flag may have gained special meaning in iCloud.

If you want a xattr preserved when it passes through iCloud, you therefore need to give it a name ending in the xattr flag S, such as co.eclecticlight.MyTest#S. Sure enough, when xattrs with that flag are passed through iCloud Drive, those xattrs are preserved even if the default rule would treat them differently. Similarly, to have a xattr stripped even when you just make a local copy of that file, append #N to it.