[RFC] statx: Define a generic OFFLINE file attribute

Background:
During the 2024 discussion on additional statx() attributes, the introduction of a generic STATX_ATTR_OFFLINE attribute was proposed and discussed as a potentially useful cross-filesystem property. The discussion highlighted use cases in HSM systems, network filesystems, and userspace tools that need to distinguish fully available files from files whose content is not immediately accessible.

Since then, Linux has gained support for pre-content access notifications through FAN_PRE_ACCESS, which provides a mechanism for userspace to supply file data before read access proceeds. This addresses a significant part of the data access path for content that is not immediately available locally.

However, userspace still lacks a standardized way to determine whether a file's contents are currently available without triggering access.

This RFC revisits the earlier discussion and proposes a minimal and filesystem-agnostic solution.

Problem Statement:
Today, userspace applications can determine many file properties through statx(), but there is no generic mechanism to discover whether file content is immediately available.

As a result:
General-purpose tools cannot distinguish between available and unavailable file content.
Filesystems may implement similar semantics differently.
Userspace software lacks a common API for querying content availability.
The recently introduced pre-content access infrastructure can hydrate content when accessed, but applications cannot discover the state beforehand.
Proposal

Introduce a new statx() attribute:
STATX_ATTR_OFFLINE

Semantic definition
A file marked with STATX_ATTR_OFFLINE satisfies the following condition:

The file's metadata is available, but the file's content is not currently guaranteed to be immediately accessible without additional retrieval, restoration, hydration, or staging work.

This definition intentionally avoids any assumptions regarding:
- storage technology
- retrieval mechanism
- userspace implementation
- caching policy
- filesystem type

The attribute describes the current availability of file content and nothing more.

Intended Usage:
Examples of applications that may benefit from a standardized OFFLINE attribute include:

- search tools
- backup software
- indexing services
- archiving software
- HSM implementations
- filesystem management utilities

Example:
statx file.dat

could return:
Attributes OFFLINE

allowing userspace applications to make informed decisions before opening the file.

Non-Goals:
This proposal does not attempt to standardize:
- synchronization status
- upload status
- conflict states
- caching policies
- retention policies
- provider-specific metadata
- graphical user interface behavior

In particular, this RFC intentionally does not propose attributes such as:
- PINNED
- SYNC_PENDING
- ERROR

as these describe userspace policy decisions rather than generic filesystem content availability.

The proposed attribute only answers one question:

Is the file content currently offline?

Filesystem Support

Filesystems may expose STATX_ATTR_OFFLINE if they can reliably determine that file data is not immediately available.

Implementation details remain filesystem specific.

A filesystem may map the attribute to:

- persistent inode flags
- internal metadata
- remote state information
- HSM state information

The RFC intentionally does not mandate how the state is stored.

Relationship to Existing Work

This proposal is intended as a direct continuation of the 2024 STATX_ATTR_OFFLINE discussion and follows the same general direction suggested there. The goal is not to introduce a new subsystem but to define a common userspace-visible semantic that can be implemented across filesystems and consumed by generic tools.

The proposal is complementary to the recently introduced pre-content access infrastructure (FAN_PRE_ACCESS). While FAN_PRE_ACCESS addresses content retrieval before access, STATX_ATTR_OFFLINE provides a mechanism for userspace to determine content availability before attempting access.

Request for Feedback

Is the proposed semantic definition sufficiently generic?

This RFC intentionally focuses on a single, narrowly scoped semantic property in order to maximize reuse across filesystems and userspace tools while minimizing policy decisions in the kernel.