Export semantics and non-hydrating materialization proof for File Provider-tagged project directories

On macOS 26.7.1 with Xcode 26.6 on Apple silicon, several directories in a development tree carry the private extended-attribute names com.apple.fileprovider.dir#N and com.apple.fileprovider.fpfs#P. On this host, the supported xattr_flags_from_name decoder returns XATTR_FLAG_NEVER_PRESERVE for the first exact name and XATTR_FLAG_NO_EXPORT for the second exact name. Apple's public API defines those flag meanings; the literal name encoding and the attributes' private values are not treated as a public semantic contract. We want a self-contained APFS compilation-input tree using descriptor-based COPYFILE_DATA for regular files, with independent inventory and hash verification and no private-xattr copying.

For this compilation-only export, does Apple support deliberate non-preservation when xattr_flags_from_name returns XATTR_FLAG_NEVER_PRESERVE, and when it returns XATTR_FLAG_NO_EXPORT for a governed SHARE operation? Separately, what public, non-hydrating API can establish that every required file is already fully materialized and that export will not trigger provider downloads? Does enumeratorForMaterializedItems establish that state for a closed descendant tree, or must each item be checked by another supported API? Can reading or hashing an item itself cause materialization?

We are asking about documented APIs, supported export behavior, and security postconditions. We are not asking to decode or preserve private attribute values. No production paths, source code, credentials, datasets, or personal information are included.

This question now blocks the same frozen 420-object compilation-only closure. Every required source member is locally readable and hashed, but we will not treat read access as proof of provider independence or deliberately trigger hydration.

Could an Apple engineer confirm whether XATTR_FLAG_NEVER_PRESERVE and XATTR_FLAG_NO_EXPORT authorize deliberate non-preservation for this cross-volume compilation export, and identify the supported non-hydrating preflight that proves the closed tree is already materialized and will not request provider downloads? If no such preflight exists, what supported export procedure should be used?

No production copy has been performed.

If you don't mind to help me better understand your question first: are you looking for a way to check if a diretory tree is fully materialized before you copy it, or are you asking how to reserve the the extended attributes when copying files out of a file provider extension? Does "export" here mean "copy"? If it does, do you do the copy from the container app of your file provider extension, or something else?

Assuming it's the former, the discussion in this thread and also TN3150 may help.

In any case, a folder being flagged as materialized doesn't mean that an item under the folder is materialized, and so to materialize the whole tree, you will need to go through all the items.

enumeratorForMaterializedItems returns an enumerator, with which you can enumerate the materialized items that the system holds, but the enumeration gives you items (NSFileProviderItemProtocol), and so for an app that doesn't know the items the file provider maintains, enumeratorForMaterializedItems doesn't help.

Best,
——
Ziqiao Chen
 Worldwide Developer Relations.

Thanks, Ziqiao.

Yes — I am primarily asking how an unrelated third-party development process can establish that a fixed, closed directory tree is fully materialized before copying it.

To clarify the terminology: by “export” in my earlier wording, I meant making a local compilation-only copy of the required source files to another owner-controlled APFS location.

This is not a SHARE/export operation such as attaching, publishing, uploading or otherwise distributing the files.

The copy is not performed by the container app of the File Provider extension and not by the File Provider extension itself. It is performed by an unrelated third-party development workflow that does not own or implement the File Provider domain.

The specific goal is:

  • the source tree remains unchanged;
  • the exact required membership is already known in advance;
  • no recursive discovery is required to define the closure;
  • no implicit File Provider download/materialization is permitted during preflight;
  • if every required item is already locally available, copy its file data into a new owner-controlled APFS compilation-input tree;
  • private File Provider extended-attribute values are not decoded or deliberately propagated.

TN3150 appears to provide a possible non-hydrating preflight mechanism using IOPOL_MATERIALIZE_DATALESS_FILES_OFF.

Could you please confirm whether the supported procedure for this case is:

  1. Apply IOPOL_MATERIALIZE_DATALESS_FILES_OFF to the thread or process.
  2. Check each exact required file/directory individually.
  3. Treat EDEADLK as evidence that accessing that item, or a required intermediate path component, would require materialization and therefore fail the preflight.
  4. Proceed only if every required item can be checked/read successfully without requiring materialization.

If that is correct, is successful access to every required item while materialization is disabled sufficient to establish that the required file data is locally available at that moment, or is another supported API/postcondition required?

There is also a race-condition question: can File Provider render an item dataless again between the successful preflight and the subsequent copy? If so, what supported coordination mechanism should an unrelated third-party copier use to keep the verified item available for the copy without initiating materialization?

For the extended-attribute operation-intent question, I believe this operation should be treated as COPY, not SHARE, because it is a private local compilation-input copy.

Could you please confirm that XATTR_OPERATION_INTENT_COPY is the appropriate intent?

And when xattr_flags_from_name reports:

  • XATTR_FLAG_NEVER_PRESERVE, should that attribute be omitted from the destination copy regardless of operation intent?
  • XATTR_FLAG_NO_EXPORT, does that restriction apply only to SHARE/export-class operations, meaning it does not by itself require omission for this local COPY operation?

We are not asking Apple to interpret the private attribute values themselves.

The source remains unchanged and no production copy has been performed.

Thanks,
Anthony

Could you please confirm whether the supported procedure for this case is:

Yeah, this sounds right. Please share if you see any issue when going along this path.

If that is correct, is successful access to every required item while materialization is disabled sufficient to establish that the required file data is locally available at that moment, or is another supported API/postcondition required?

The technote covers how to determine a file is dataless by checking fileStat.st_flags & SF_DATALESS. I'd follow that guideline, rather than depending on the error.

There is also a race-condition question: can File Provider render an item dataless again between the successful preflight and the subsequent copy?

Yeah, this is perfectly possible, but does it really impact your procedure? Consider the following:

  1. You do a preflight, and determine file A is dataless.
  2. File A is materialized for some reason.
  3. You give up the copy based on 1.
  4. Your next preflight catches file A, and you do the copy.

The other way around:

  1. You do a preflight, and determine file A is materialized.
  2. File A turns dataless for some reason.
  3. You try to do the copy based on 1.
  4. You hit the EDEADLK error, and give up the copy.

Both cases seem to be fine.

Regarding the attributes, I'd see if other folks have more insight.

Finally, I see "no production copy has been performed" in your posts, and am wondering if your posts were AI-written. It doesn't matter because the text is quite fluent. Just for my curiosity...

Best,
——
Ziqiao Chen
 Worldwide Developer Relations.