Portable filesystem value types and caller-owned opaque handles. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for fw_if_fs_types.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	fw_fs_caps_t
	Static properties and workspace requirements of one bound port. More...
struct	fw_fs_datetime_t
	Backend-neutral civil time with nanosecond precision. More...
struct	fw_fs_timestamp_t
	One portable timestamp and independent availability facts. More...
struct	fw_fs_stat_t
	Result of a portable metadata query. More...
struct	fw_fs_dirent_t
	One directory entry, valid only for the callback invocation. More...
struct	fw_fs_dirent_value_t
	Stable caller-owned value returned by fw_fs_dir_next. More...
struct	fw_fs_space_t
	Portable volume usage snapshot. More...
struct	fw_fs_namespace_t
	Independently injectable path/namespace facade. More...
struct	fw_fs_stream_port_t
	Independently injectable open-stream facade. More...
struct	fw_fs_transaction_port_t
	Independently injectable staged-transaction facade. More...
struct	fw_fs_t
	One complete composition-root filesystem binding. More...
struct	fw_fs_file_t
	Caller-owned open file; fields are private to the facade. More...
struct	fw_fs_dir_t
	Caller-owned open directory cursor; fields are private to the facade. More...
struct	fw_fs_transaction_t
	Caller-owned transaction; fields are private to the facade. More...

Typedefs
typedef ra8_err_t(*	fw_fs_list_fn_t) (void ctx, const fw_fs_dirent_t entry, bool *out_continue)
	Bounded list callback.
typedef struct fw_fs_namespace_iface	fw_fs_namespace_iface_t
typedef struct fw_fs_stream_iface	fw_fs_stream_iface_t
typedef struct fw_fs_transaction_iface	fw_fs_transaction_iface_t
typedef ra8_err_t(*	fw_fs_validate_fn_t) (void ctx, fw_fs_file_t staged)
	Validate staged bytes through a read-only generic file handle.

Enumerations
enum	fw_fs_limits_t : uint16_t { k_fw_fs_path_cap = 512U }
	Interface-wide hard bounds used before a backend is called. More...
enum	fw_fs_node_type_t : uint8_t { k_fw_fs_node_none = 0U , k_fw_fs_node_file = 1U , k_fw_fs_node_directory = 2U , k_fw_fs_node_symlink = 3U , k_fw_fs_node_other = 4U }
	Filesystem node kind reported by fw_fs_stat. More...
enum	fw_fs_open_mode_t : uint8_t { k_fw_fs_open_read = 0U , k_fw_fs_open_write_truncate = 1U , k_fw_fs_open_append = 2U , k_fw_fs_open_create_new = 3U }
	Open intent for fw_fs_open. More...
enum	fw_fs_transaction_policy_t : uint8_t { k_fw_fs_txn_create_new = 0U , k_fw_fs_txn_replace_atomic = 1U }
	Destination policy for a staged transaction. More...
enum	fw_fs_capability_t : uint32_t { k_fw_fs_cap_namespace = 1UL << 0U , k_fw_fs_cap_stream = 1UL << 1U , k_fw_fs_cap_space_query = 1UL << 2U , k_fw_fs_cap_same_volume_rename = 1UL << 3U , k_fw_fs_cap_atomic_replace = 1UL << 4U , k_fw_fs_cap_atomic_noreplace = 1UL << 5U , k_fw_fs_cap_create_exclusive = 1UL << 6U , k_fw_fs_cap_file_sync = 1UL << 7U , k_fw_fs_cap_durable_file_sync = 1UL << 8U , k_fw_fs_cap_durable_directory_sync = 1UL << 9U , k_fw_fs_cap_transactions = 1UL << 10U , k_fw_fs_cap_symlinks = 1UL << 11U , k_fw_fs_cap_rejects_symlink_walk = 1UL << 12U , k_fw_fs_cap_case_sensitive = 1UL << 13U , k_fw_fs_cap_removable_media = 1UL << 14U , k_fw_fs_cap_thread_safe = 1UL << 15U , k_fw_fs_cap_created_time = 1UL << 16U , k_fw_fs_cap_modified_time = 1UL << 17U , k_fw_fs_cap_accessed_time = 1UL << 18U }
	Capability bits returned in fw_fs_caps_t.flags. More...

Detailed Description

Portable filesystem value types and caller-owned opaque handles.

Tag: [Ring 2 / Interface] {World: Any}

These types describe filesystem intent without naming POSIX, FAT, a block device, an MCU, or an RTOS. Concrete ports bind private vtables and opaque contexts into the small handles below. Backend-specific file and transaction state is supplied by the caller at open/begin time; no handle owns dynamically allocated memory.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file fw_if_fs_types.h.

Typedef Documentation

◆ fw_fs_list_fn_t

typedef ra8_err_t(* fw_fs_list_fn_t) (void *ctx, const fw_fs_dirent_t *entry, bool *out_continue)

Bounded list callback.

Parameters

[in]	ctx	Caller cookie.
[in]	entry	Entry valid for this call only.
[in,out]	out_continue	Set false to stop delivering entries.

Returns: k_ra8_ok to continue/stop normally, or an error to abort delivery.

Definition at line 182 of file fw_if_fs_types.h.

◆ fw_fs_namespace_iface_t

typedef struct fw_fs_namespace_iface fw_fs_namespace_iface_t

Definition at line 184 of file fw_if_fs_types.h.

◆ fw_fs_stream_iface_t

typedef struct fw_fs_stream_iface fw_fs_stream_iface_t

Definition at line 185 of file fw_if_fs_types.h.

◆ fw_fs_transaction_iface_t

typedef struct fw_fs_transaction_iface fw_fs_transaction_iface_t

Definition at line 186 of file fw_if_fs_types.h.

◆ fw_fs_validate_fn_t

typedef ra8_err_t(* fw_fs_validate_fn_t) (void *ctx, fw_fs_file_t *staged)

Validate staged bytes through a read-only generic file handle.

Parameters

[in]	ctx	Caller cookie.
[in]	staged	Open read-only view of the staged artifact.

Returns: k_ra8_ok only when the artifact is safe to publish.

Definition at line 252 of file fw_if_fs_types.h.

Enumeration Type Documentation

◆ fw_fs_capability_t

enum fw_fs_capability_t : uint32_t

Capability bits returned in fw_fs_caps_t.flags.

Enumerator
k_fw_fs_cap_namespace	Metadata and namespace operations are available.
k_fw_fs_cap_stream	Regular-file stream operations are available.
k_fw_fs_cap_space_query	Volume capacity and available bytes can be queried.
k_fw_fs_cap_same_volume_rename	Rename is supported within one backend volume.
k_fw_fs_cap_atomic_replace	Rename can atomically replace an existing destination.
k_fw_fs_cap_atomic_noreplace	Rename can atomically reject an existing destination.
k_fw_fs_cap_create_exclusive	Open can atomically require that its leaf be absent.
k_fw_fs_cap_file_sync	An explicit file-sync operation is available.
k_fw_fs_cap_durable_file_sync	Successful file sync reaches durable media.
k_fw_fs_cap_durable_directory_sync	Namespace changes can be made durable.
k_fw_fs_cap_transactions	Staged publication operations are available.
k_fw_fs_cap_symlinks	Symbolic links may be represented by the backend.
k_fw_fs_cap_rejects_symlink_walk	Path traversal refuses symbolic-link components.
k_fw_fs_cap_case_sensitive	Path-component comparisons are case-sensitive.
k_fw_fs_cap_removable_media	The backing volume may disappear at runtime.
k_fw_fs_cap_thread_safe	Independent calls may execute concurrently.
k_fw_fs_cap_created_time	Creation timestamps may be reported as valid.
k_fw_fs_cap_modified_time	Modification timestamps may be reported as valid.
k_fw_fs_cap_accessed_time	Access timestamps may be reported as valid.

Definition at line 61 of file fw_if_fs_types.h.

◆ fw_fs_limits_t

enum fw_fs_limits_t : uint16_t

Interface-wide hard bounds used before a backend is called.

Enumerator
k_fw_fs_path_cap	Largest portable path including its NUL.

Definition at line 33 of file fw_if_fs_types.h.

◆ fw_fs_node_type_t

enum fw_fs_node_type_t : uint8_t

Filesystem node kind reported by fw_fs_stat.

Enumerator
k_fw_fs_node_none	No node exists at the path.
k_fw_fs_node_file	Regular byte stream.
k_fw_fs_node_directory	Directory.
k_fw_fs_node_symlink	Symbolic link, if observable.
k_fw_fs_node_other	Backend-specific non-file node.

Definition at line 38 of file fw_if_fs_types.h.

◆ fw_fs_open_mode_t

enum fw_fs_open_mode_t : uint8_t

Open intent for fw_fs_open.

Enumerator
k_fw_fs_open_read	Existing file, read-only.
k_fw_fs_open_write_truncate	Create/truncate, write-only.
k_fw_fs_open_append	Create/append, write-only.
k_fw_fs_open_create_new	Create only when leaf is absent.

Definition at line 47 of file fw_if_fs_types.h.

◆ fw_fs_transaction_policy_t

enum fw_fs_transaction_policy_t : uint8_t

Destination policy for a staged transaction.

Enumerator
k_fw_fs_txn_create_new	Commit only when destination is absent.
k_fw_fs_txn_replace_atomic	Atomically replace an existing file.

Definition at line 55 of file fw_if_fs_types.h.

Data Structures

Typedefs

Enumerations