mdl_library.c File Reference

Portable bounded tracked-library enumeration and tree removal. More...

#include "mdl_library.h"
#include <stdint.h>
#include <string.h>
#include "mdl_sanitize.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_library.c:

Go to the source code of this file.

Data Structures
struct	mdl_library_enumeration_t
	State threaded through one immediate-library enumeration. More...

Functions
mdl_library_policy_t	mdl_library_policy_default (void)
	Return the production library traversal policy.
ra8_err_t	mdl_library_workspace_init (mdl_library_workspace_t *workspace, void *directory_workspace, uint32_t directory_workspace_bytes)
	Bind caller-owned directory storage to a reusable library workspace.
static void	internal_library_workspace_reset (mdl_library_workspace_t *workspace)
	Clear traversal state while preserving caller cursor storage.
static ra8_err_t	internal_library_policy (const mdl_library_policy_t *policy)
	Validate a caller-selected policy against hard ceilings.
static ra8_err_t	internal_library_leaf (const mdl_storage_t *storage, const fw_fs_dirent_value_t *entry, size_t *out_length)
	Validate and measure one borrowed backend leaf name.
static ra8_err_t	internal_library_visit (mdl_library_enumeration_t *walk, const fw_fs_dirent_value_t *entry, bool *out_continue)
	Authenticate and deliver one stable cursor entry.
static ra8_err_t	internal_library_close (fw_fs_dir_t *directory, ra8_err_t first)
	Preserve the first traversal error while always consuming a cursor.
static ra8_err_t	internal_library_root (mdl_storage_t *storage, const char *root_path, bool *out_exists)
	Validate one library root before cursor open.
static ra8_err_t	internal_library_enumerate (mdl_library_enumeration_t *walk, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace)
	Advance one cursor while authenticating entries between next calls.
ra8_err_t	mdl_library_for_each (mdl_storage_t *storage, const char *out_dir, mdl_state_t *state_scratch, mdl_library_workspace_t *workspace, const mdl_library_policy_t *policy, mdl_library_fn callback, void *callback_ctx)
	Visit every authenticated tracked series under a library root.
static ra8_err_t	internal_library_take_operation (const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace)
	Consume one removal namespace-operation budget unit.
static ra8_err_t	internal_library_first_child (mdl_storage_t *storage, const char *path, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace, fw_fs_dirent_value_t *out, bool *out_present)
	Copy at most one child then close before any namespace mutation.
static ra8_err_t	internal_library_act_on_node (mdl_storage_t *storage, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace, const char *path, fw_fs_stat_t node)
	Act on one revalidated child node according to its type.
static ra8_err_t	internal_library_remove_child (mdl_storage_t *storage, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace, const fw_fs_dirent_value_t *child)
	Remove or descend into one captured child.
static ra8_err_t	internal_library_remove_root (mdl_storage_t *storage, const char *dir, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace)
	Validate and retain the root of one removal traversal.
static ra8_err_t	internal_library_remove_walk (mdl_storage_t *storage, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace)
	Execute iterative post-order removal from a retained valid root.
ra8_err_t	mdl_library_remove_tree (mdl_storage_t *storage, const char *dir, const mdl_library_policy_t *policy, mdl_library_workspace_t *workspace)
	Remove one canonical directory tree through portable namespace calls.

Variables
static const char	s_state_basename [] = ".mdl_state"
	Logical marker basename within one tracked series.

Detailed Description

Portable bounded tracked-library enumeration and tree removal.

Uses only the injected fw_fs namespace/stream contracts and fixed caller-owned state; no host directory stream or recursive call exists.

Copyright

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

Definition in file mdl_library.c.

Function Documentation

internal_library_act_on_node()

ra8_err_t internal_library_act_on_node ( mdl_storage_t * storage, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace, const char * path, fw_fs_stat_t node )

static

Act on one revalidated child node according to its type.

Pushes a directory onto the DFS stack, rejects a symlink, or unlinks a regular file.

Parameters

[in,out]	storage	Portable namespace binding.
[in]	policy	Active traversal limits.
[in,out]	workspace	Active DFS stack and counters.
[in]	path	Canonical path of the revalidated node.
[in]	node	Freshly stat'd node value for path.

Returns

Canonical child-processing status.

Return values

k_ra8_ok	The directory was pushed or the file was removed.
k_ra8_err_access_denied	The node is a symlink.
k_ra8_err_invalid_size	The DFS depth budget was exhausted.
k_ra8_err_invalid_arg	The node is neither a directory, symlink, nor a regular file.

Precondition

storage, policy, workspace, and path are non-NULL.

node was produced by a fresh fw_fs_stat on path.

Postcondition

Success either increments workspace->depth exactly once or removes exactly one file.

A symlink is rejected without being followed, opened, or unlinked.

Note

Not thread-safe with respect to concurrent mutation of storage.

Since

0.1.0

Definition at line 430 of file mdl_library.c.

References mdl_library_workspace_t::depth, mdl_storage_t::fs, fw_fs_unlink(), internal_library_take_operation(), k_fw_fs_node_directory, k_fw_fs_node_file, k_fw_fs_node_symlink, k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_library_policy_t::max_depth, memcpy(), fw_fs_t::names, mdl_library_workspace_t::paths, RA8_INTERNAL, strlen(), and fw_fs_stat_t::type.

Referenced by internal_library_remove_child().

internal_library_close()

ra8_err_t internal_library_close ( fw_fs_dir_t * directory, ra8_err_t first )

static

Preserve the first traversal error while always consuming a cursor.

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Parameters

[in,out]	directory	Directory handle owned by the caller.
[in]	first	First text fragment.

Returns

Operation status.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition

Every required pointer is non-null and remains valid for the call.

Lengths and capacities describe complete referenced objects without overflow.

Postcondition

Documented outputs and the return value describe the same outcome.

A rejected or failed operation is never reported as successful.

Note

Thread safety follows ownership of the supplied context; no synchronization is added.

Since

Version 0.1.0

Definition at line 211 of file mdl_library.c.

References fw_fs_dir_close(), fw_fs_dir_t::is_open, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_library_enumerate(), and internal_library_first_child().

internal_library_enumerate()

ra8_err_t internal_library_enumerate ( mdl_library_enumeration_t * walk, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace )

static

Advance one cursor while authenticating entries between next calls.

Parameters

[in,out]	walk	Active enumeration dependencies and callback.
[in]	policy	Explicit entry limit.
[in,out]	workspace	Cursor storage and exact counters.

Returns

Cursor, authentication, callback, or close status.

Precondition

Required pointers are non-NULL and the root is a real directory.

Postcondition

The cursor is consumed on every return path.

Note

No backend lock is held during stat, state I/O, or user callback work.

Since

0.1.0

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition

Every required pointer is non-null and remains valid for the call.

Postcondition

Documented outputs and the return value describe the same outcome.

Definition at line 272 of file mdl_library.c.

References mdl_library_workspace_t::directory_workspace, mdl_library_workspace_t::directory_workspace_bytes, mdl_library_workspace_t::entries, fw_fs_dir_next(), fw_fs_dir_open(), internal_library_close(), internal_library_visit(), k_ra8_err_invalid_size, k_ra8_ok, mdl_library_policy_t::max_entries, RA8_INTERNAL, and mdl_library_workspace_t::required_entries.

Referenced by mdl_library_for_each().

internal_library_first_child()

ra8_err_t internal_library_first_child ( mdl_storage_t * storage, const char * path, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace, fw_fs_dirent_value_t * out, bool * out_present )

static

Copy at most one child then close before any namespace mutation.

Parameters

[in,out]	storage	Portable namespace binding.
[in]	path	Current canonical directory path.
[in]	policy	Active operation budget.
[in,out]	workspace	Cursor storage and operation counter.
[out]	out	Stable copied child value.
[out]	out_present	True when a child was copied.

Returns

Budget, cursor, next, or close status.

Precondition

Required pointers are non-NULL and no cursor is open.

Postcondition

No cursor remains open and out_present is initialized on success.

Note

Three operations are reserved atomically so close can never be skipped.

Since

0.1.0

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition

Every required pointer is non-null and remains valid for the call.

Postcondition

Documented outputs and the return value describe the same outcome.

Definition at line 381 of file mdl_library.c.

References mdl_library_workspace_t::directory_workspace, mdl_library_workspace_t::directory_workspace_bytes, mdl_storage_t::fs, fw_fs_dir_next(), fw_fs_dir_open(), internal_library_close(), k_ra8_err_invalid_size, k_ra8_ok, mdl_library_policy_t::max_operations, fw_fs_t::names, mdl_library_workspace_t::operations, and RA8_INTERNAL.

Referenced by internal_library_remove_walk().

internal_library_leaf()

ra8_err_t internal_library_leaf ( const mdl_storage_t * storage, const fw_fs_dirent_value_t * entry, size_t * out_length )

static

Validate and measure one borrowed backend leaf name.

Cross-checks the reported byte count, binding component cap, NUL, and lexical single-segment rules before any path composition.

Parameters

[in]	storage	Initialized filesystem binding.
[in]	entry	Borrowed directory entry.
[out]	out_length	Verified leaf length.

Returns

Canonical backend-contract status.

Return values

k_ra8_ok	The complete leaf is safe to compose.
k_ra8_err_invalid_state	The backend supplied inconsistent metadata.
k_ra8_err_invalid_arg	The leaf is not one safe path segment.

Precondition

All pointers are non-NULL.

entry is valid for the active list callback.

Postcondition

Success initializes out_length.

No input or filesystem state is modified.

Note

The hard path cap bounds strnlen even for a faulty backend.

Since

0.1.0

Definition at line 118 of file mdl_library.c.

References fw_fs_t::caps, mdl_storage_t::fs, k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, fw_fs_dirent_value_t::name, fw_fs_dirent_value_t::name_bytes, fw_fs_caps_t::name_max_bytes, RA8_INTERNAL, strcmp(), and strnlen().

Referenced by internal_library_remove_child().

internal_library_policy()

ra8_err_t internal_library_policy ( const mdl_library_policy_t * policy )

static

Validate a caller-selected policy against hard ceilings.

Rejects zero work budgets and values exceeding fixed workspace bounds.

Parameters

[in]

policy

Candidate traversal policy.

Returns

Canonical policy status.

Return values

k_ra8_ok	Every bound is usable.
k_ra8_err_invalid_arg	The pointer or one lower bound is invalid.
k_ra8_err_invalid_size	One field exceeds its hard ceiling.

Precondition

policy may be NULL.

No filesystem operation is active.

Postcondition

The policy is unchanged.

No dependency state is accessed.

Note

Thread-safe and side-effect free.

Since

0.1.0

Definition at line 87 of file mdl_library.c.

References k_mdl_library_depth_limit, k_mdl_library_entry_limit, k_mdl_library_operation_limit, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_library_policy_t::max_depth, mdl_library_policy_t::max_entries, mdl_library_policy_t::max_operations, and RA8_INTERNAL.

Referenced by mdl_library_for_each(), and mdl_library_remove_tree().

internal_library_remove_child()

ra8_err_t internal_library_remove_child ( mdl_storage_t * storage, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace, const fw_fs_dirent_value_t * child )

static

Remove or descend into one captured child.

Revalidates the stable leaf and node type after listdir closes, then delegates to internal_library_act_on_node.

Parameters

[in,out]	storage	Portable namespace binding.
[in]	policy	Active traversal limits.
[in,out]	workspace	Active DFS stack and counters.
[in]	child	Stable copied child.

Returns

Canonical child-processing status.

Return values

k_ra8_ok	The file was removed or directory was pushed.
k_ra8_err_access_denied	A symlink was encountered.

Precondition

All pointers are non-NULL and the current stack path is canonical.

child was produced by internal_library_first_child.

Postcondition

Success removes one file or increments depth exactly once.

Failure never follows or operates through a symbolic link.

Note

Stat/list type disagreement is treated as a concurrent-mutation error.

Since

0.1.0

Definition at line 472 of file mdl_library.c.

References mdl_library_workspace_t::depth, mdl_library_workspace_t::entries, fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), internal_library_act_on_node(), internal_library_leaf(), internal_library_take_operation(), k_fw_fs_path_cap, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, mdl_library_policy_t::max_entries, mdl_path_join(), fw_fs_dirent_value_t::name, fw_fs_t::names, mdl_library_workspace_t::paths, RA8_INTERNAL, mdl_library_workspace_t::required_entries, fw_fs_dirent_value_t::type, and fw_fs_stat_t::type.

Referenced by internal_library_remove_walk().

internal_library_remove_root()

ra8_err_t internal_library_remove_root ( mdl_storage_t * storage, const char * dir, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace )

static

Validate and retain the root of one removal traversal.

Parameters

[in,out]	storage	Portable namespace binding.
[in]	dir	Canonical candidate root.
[in]	policy	Validated removal policy.
[in,out]	workspace	Initialized idle traversal workspace.

Returns

Canonical root validation or stat status.

Precondition

Required pointers are non-NULL and policy bounds are valid.

workspace has a live caller-owned entry binding.

Postcondition

Success retains dir at stack depth zero.

An absent root succeeds without retaining a path.

Note

Symlinks and non-directory nodes fail closed.

Since

0.1.0

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 525 of file mdl_library.c.

References mdl_library_workspace_t::entry_limit, fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), internal_library_take_operation(), internal_library_workspace_reset(), k_fw_fs_node_directory, k_fw_fs_node_symlink, k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_library_policy_t::max_entries, memcpy(), fw_fs_t::names, mdl_library_workspace_t::paths, RA8_INTERNAL, strnlen(), and fw_fs_stat_t::type.

Referenced by mdl_library_remove_tree().

internal_library_remove_walk()

ra8_err_t internal_library_remove_walk ( mdl_storage_t * storage, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace )

static

Execute iterative post-order removal from a retained valid root.

Parameters

[in,out]	storage	Portable namespace binding.
[in]	policy	Validated removal policy.
[in,out]	workspace	Active root path, stack, and counters.

Returns

Canonical traversal or namespace status.

Precondition

Required pointers are non-NULL and stack depth zero holds a directory.

No directory listing handle is live on entry.

Postcondition

Success removes the complete root tree.

Failure reports the first fault after any already completed deletion.

Note

Each list handle closes before stat, descent, unlink, or rmdir.

Since

0.1.0

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 575 of file mdl_library.c.

References mdl_library_workspace_t::depth, mdl_storage_t::fs, fw_fs_rmdir(), internal_library_first_child(), internal_library_remove_child(), internal_library_take_operation(), k_ra8_ok, fw_fs_t::names, mdl_library_workspace_t::paths, and RA8_INTERNAL.

Referenced by mdl_library_remove_tree().

internal_library_root()

ra8_err_t internal_library_root ( mdl_storage_t * storage, const char * root_path, bool * out_exists )

static

Validate one library root before cursor open.

Parameters

[in,out]	storage	Portable dependency binding.
[in]	root_path	Canonical library root.
[out]	out_exists	Whether the validated root exists.

Returns

Root stat and type status; an absent root is an empty library.

Precondition

Required pointers are non-NULL.

Postcondition

No cursor or stream remains open.

Note

Symlink roots fail closed.

Since

0.1.0

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition

Every required pointer is non-null and remains valid for the call.

Postcondition

Documented outputs and the return value describe the same outcome.

Definition at line 239 of file mdl_library.c.

References fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), k_fw_fs_node_directory, k_fw_fs_node_symlink, k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_ok, fw_fs_t::names, and fw_fs_stat_t::type.

Referenced by mdl_library_for_each().

internal_library_take_operation()

ra8_err_t internal_library_take_operation ( const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace )

static

Consume one removal namespace-operation budget unit.

Increments before a dependency call and rejects cap+1 without calling it.

Parameters

[in]	policy	Active explicit traversal policy.
[in,out]	workspace	Active traversal counters.

Returns

Operation-budget status.

Return values

k_ra8_ok	One operation is reserved.
k_ra8_err_invalid_size	The exact budget was already consumed.

Precondition

Both pointers are non-NULL.

workspace->operations never exceeds the policy bound.

Postcondition

Success increments the counter exactly once.

Failure leaves the counter unchanged.

Note

Call immediately before each namespace operation.

Since

0.1.0

Definition at line 350 of file mdl_library.c.

References k_ra8_err_invalid_size, k_ra8_ok, mdl_library_policy_t::max_operations, mdl_library_workspace_t::operations, and RA8_INTERNAL.

Referenced by internal_library_act_on_node(), internal_library_remove_child(), internal_library_remove_root(), and internal_library_remove_walk().

internal_library_visit()

ra8_err_t internal_library_visit ( mdl_library_enumeration_t * walk, const fw_fs_dirent_value_t * entry, bool * out_continue )

static

Authenticate and deliver one stable cursor entry.

Ignores non-directories and untracked directories; every existing marker must authenticate before the user callback can observe it.

Parameters

[in,out]	walk	Active post-list enumeration state.
[in]	entry	Stable copied directory entry.
[out]	out_continue	User callback continuation decision.

Returns

Canonical stat, authentication, or callback status.

Return values

k_ra8_ok

The entry was ignored, visited, or stopped cleanly.

Precondition

All pointers are non-NULL and no backend lock is held.

entry was validated by guarded cursor dispatch.

Postcondition

The callback runs only after authenticated state recovery.

out_continue is initialized on success.

Note

Filesystem calls occur strictly between cursor-next operations.

Since

0.1.0

Definition at line 154 of file mdl_library.c.

References fw_fs_stat_t::exists, fw_fs_stat(), k_fw_fs_node_directory, k_fw_fs_path_cap, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, mdl_path_join(), mdl_state_load_authenticated(), mdl_state_probe(), fw_fs_dirent_value_t::name, RA8_INTERNAL, s_state_basename, fw_fs_dirent_value_t::type, and fw_fs_stat_t::type.

Referenced by internal_library_enumerate().

internal_library_workspace_reset()

void internal_library_workspace_reset ( mdl_library_workspace_t * workspace )

static

Clear traversal state while preserving caller cursor storage.

Parameters

[in,out]

workspace

Initialized reusable library workspace.

Precondition

workspace is non-NULL and has a valid cursor binding.

No traversal currently borrows the workspace.

Postcondition

All counters and retained DFS paths are reset.

Cursor storage pointer and extent are unchanged.

Note

Backend cursor bytes are initialized by each successful open.

Since

0.1.0

Advances bounded filesystem cursors without retaining backend locks. Callbacks and namespace mutations run only after cursor close.

Definition at line 62 of file mdl_library.c.

References mdl_library_workspace_t::depth, mdl_library_workspace_t::entries, mdl_library_workspace_t::entry_limit, memset(), mdl_library_workspace_t::operations, mdl_library_workspace_t::paths, RA8_INTERNAL, and mdl_library_workspace_t::required_entries.

Referenced by internal_library_remove_root(), and mdl_library_for_each().

mdl_library_for_each()

ra8_err_t mdl_library_for_each ( mdl_storage_t * storage, const char * out_dir, mdl_state_t * state_scratch, mdl_library_workspace_t * workspace, const mdl_library_policy_t * policy, mdl_library_fn callback, void * callback_ctx )

nodiscard

Visit every authenticated tracked series under a library root.

Validates the canonical root, enumerates at most max_entries + 1 immediate entries to distinguish the exact cap from cap+1, and authenticates both state generations before invoking callback. An absent root is an empty library. Clean callback stop succeeds; callback, list, stat, state-read, and close errors propagate.

Parameters

[in,out]	storage	Initialized portable filesystem binding.
[in]	out_dir	Canonical library-root path.
[in,out]	state_scratch	Caller-owned state model reused per callback.
[in,out]	workspace	Initialized caller-owned cursor storage.
[in]	policy	Explicit bounded traversal policy.
[in]	callback	Authenticated-series visitor.
[in,out]	callback_ctx	Opaque callback context, possibly NULL.

Returns

Canonical traversal, authentication, or callback status.

Return values

k_ra8_ok	Enumeration completed, stopped cleanly, or root was absent.
k_ra8_err_invalid_size	The immediate entry cap was exceeded.
k_ra8_err_invalid_arg	A binding, policy, path, or root type is invalid.
other	A namespace, stream, authentication, close, or callback error.

Precondition

Required pointers are non-NULL and out_dir is canonical.

Storage, state scratch, and workspace are exclusively owned for the call.

The workspace meets storage->fs->caps.directory_workspace_*.

Postcondition

Every callback receives one authenticated state and runs at most once for each accepted immediate directory entry.

Enumeration never modifies the library namespace.

Note

Not thread-safe because storage and state scratch are reused.

Since

0.1.0

Definition at line 304 of file mdl_library.c.

References mdl_library_workspace_t::directory_workspace, mdl_library_workspace_t::directory_workspace_bytes, mdl_library_workspace_t::entry_limit, mdl_storage_t::fs, internal_library_enumerate(), internal_library_policy(), internal_library_root(), internal_library_workspace_reset(), k_ra8_err_invalid_arg, k_ra8_ok, and mdl_library_policy_t::max_entries.

Referenced by mdl_app_run_list(), and mdl_app_run_update_all().

mdl_library_policy_default()

mdl_library_policy_t mdl_library_policy_default ( void )

nodiscard

Return the production library traversal policy.

Selects the complete fixed entry, operation, and depth ceilings; tests may pass a stricter policy to exercise every boundary.

Returns

Policy containing all production hard ceilings.

Return values

mdl_library_policy_t

Complete bounded production policy.

Precondition

No initialization or filesystem binding is required.

The returned value is copied by the caller before optional narrowing.

Postcondition

Every field is nonzero and within its corresponding hard ceiling.

No global or caller state is modified.

Note

Thread-safe and side-effect free.

Since

0.1.0

Definition at line 29 of file mdl_library.c.

References k_mdl_library_depth_limit, k_mdl_library_entry_limit, and k_mdl_library_operation_limit.

Referenced by mdl_app_run_list(), mdl_app_run_remove(), and mdl_app_run_update_all().

mdl_library_remove_tree()

ra8_err_t mdl_library_remove_tree ( mdl_storage_t * storage, const char * dir, const mdl_library_policy_t * policy, mdl_library_workspace_t * workspace )

nodiscard

Remove one canonical directory tree through portable namespace calls.

Performs a non-recursive iterative post-order traversal using fw_fs_dir_open, fw_fs_dir_next, fw_fs_dir_close, fw_fs_stat, fw_fs_unlink, and fw_fs_rmdir. Symlinks and other special nodes are refused, never followed. Every bound and dependency failure is returned even when prior children were already removed, making partial deletion explicit.

Parameters

[in,out]	storage	Initialized portable filesystem binding.
[in]	dir	Canonical non-root directory to remove.
[in]	policy	Explicit entry, depth, and operation limits.
[in,out]	workspace	Initialized iterative path stack and counters.

Returns

Canonical removal or traversal status.

Return values

k_ra8_ok	The tree was removed or was already absent.
k_ra8_err_access_denied	A symbolic link or protected root was seen.
k_ra8_err_invalid_size	A path, entry, depth, or operation cap was exceeded.
k_ra8_err_invalid_arg	A binding, policy, path, or node type is invalid.
other	A list, stat, unlink, or rmdir failure propagated unchanged.

Precondition

Required pointers are non-NULL, dir is canonical, and workspaces are idle.

workspace was initialized by mdl_library_workspace_init.

The caller has authenticated that dir is the intended tracked series.

Postcondition

Success leaves no node at dir.

Failure never accesses a path not lexically contained beneath dir.

Note

Not thread-safe against concurrent mutation of the same tree.

Since

0.1.0

Definition at line 609 of file mdl_library.c.

References mdl_library_workspace_t::directory_workspace, mdl_library_workspace_t::directory_workspace_bytes, mdl_storage_t::fs, internal_library_policy(), internal_library_remove_root(), internal_library_remove_walk(), k_ra8_err_invalid_arg, k_ra8_ok, and mdl_library_workspace_t::paths.

Referenced by mdl_app_run_remove().

mdl_library_workspace_init()

ra8_err_t mdl_library_workspace_init ( mdl_library_workspace_t * workspace, void * directory_workspace, uint32_t directory_workspace_bytes )

nodiscard

Bind caller-owned directory storage to a reusable library workspace.

The storage must satisfy the selected filesystem's advertised directory-workspace size and alignment. Its size is independent of the number of library entries; enumeration retains only one value.

Parameters

[out]	workspace	Library workspace to initialize.
[in,out]	directory_workspace	Caller-owned backend cursor state.
[in]	directory_workspace_bytes	Accessible workspace extent.

Returns

Workspace binding status.

Return values

k_ra8_ok	The workspace is initialized and idle.
k_ra8_err_invalid_arg	A pointer or zero capacity is invalid.

Precondition

directory_workspace addresses the reported writable extent.

Neither storage region is in use by another traversal.

Postcondition

Success retains the workspace pointer and extent and clears counters.

Failure does not initialize a usable workspace.

Note

No memory is allocated or ownership transferred.

Since

0.1.0

Definition at line 36 of file mdl_library.c.

References k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_storage_init().

Variable Documentation

s_state_basename

const char s_state_basename[] = ".mdl_state"

static

Logical marker basename within one tracked series.

Definition at line 18 of file mdl_library.c.

Referenced by internal_library_visit().