fw_if_fs_posix_contracts_internal.h File Reference

File-local contracts for the confined POSIX filesystem adapter. More...

#include <sys/stat.h>
#include "fw_if_fs_posix_internal.h"
#include "ra8_attributes.h"

Include dependency graph for fw_if_fs_posix_contracts_internal.h:

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

Go to the source code of this file.

Functions
static ra8_err_t	internal_component_copy (const char *start, uint16_t length, char *out)
	Copy one bounded path component into a fixed local buffer.
static ra8_err_t	internal_intermediate_check (int parent_fd, const char *component, posix_root_alias_t *out_alias)
	Validate one directory component without following a symbolic link.
static ra8_err_t	internal_next_component (const char **cursor, char *out_name, uint16_t *out_length)
	Scan and copy the next slash-delimited component of a cursor.
static ra8_err_t	internal_parent_open_step (int *current, const char *name)
	Descend into one intermediate path component, retiring the old parent.
static fw_fs_node_type_t	internal_node_type (mode_t mode)
	Convert a POSIX mode into a portable node kind.
static ra8_err_t	internal_native_stat (fw_fs_posix_state_t *state, const char *path, struct stat *out, bool *out_exists)
	Query native metadata without following the final component.
static ra8_err_t	internal_stat (void *ctx, const char *path, fw_fs_stat_t *out)
	Produce portable metadata for one path below the confined root.
static ra8_err_t	internal_directory_open (fw_fs_posix_state_t *state, const char *path, int *out_fd)
	Open a confined directory without following its final component.
static ra8_err_t	internal_mkdir (void *ctx, const char *path)
	Create one confined directory with no implicit parent creation.
static ra8_err_t	internal_unlink (void *ctx, const char *path)
	Remove one confined regular file while refusing directories and links.
static ra8_err_t	internal_rmdir (void *ctx, const char *path)
	Remove one confined empty real directory.
static ra8_err_t	internal_rename_noreplace (int old_fd, const char *old_leaf, int new_fd, const char *new_leaf)
	Perform a host atomic no-replace rename without a TOCTOU fallback.
static ra8_err_t	internal_rename_validate_endpoints (fw_fs_posix_state_t *state, const char *old_path, const char *new_path)
	Validate that a rename's source exists and neither endpoint is a symlink.
static ra8_err_t	internal_rename (void *ctx, const char *old_path, const char *new_path, bool replace)
	Rename within the selected root without following either leaf.
static ra8_err_t	internal_space (void *ctx, fw_fs_space_t *out)
	Query confined-root volume byte totals with fstatvfs.
static ra8_err_t	internal_stage_open (fw_fs_posix_state_t *state, posix_transaction_state_t *txn)
	Create an exclusive sibling stage after bounded collision retries.
static ra8_err_t	internal_txn_begin (void *ctx, void *transaction_state, uint32_t state_bytes, const char *destination, fw_fs_transaction_policy_t policy)
	Begin a staged POSIX create-new or atomic-replacement transaction.
static ra8_err_t	internal_txn_write (void *ctx, void *transaction_state, const uint8_t *src, uint32_t len, uint32_t *out_written)
	Append bytes to an open POSIX transaction stage.
static ra8_err_t	internal_txn_seek (void *ctx, void *transaction_state, uint64_t offset)
	Seek within the open POSIX stage for bounded header or table backfill.
static ra8_err_t	internal_txn_validate (void *ctx, void *transaction_state, fw_fs_validate_fn_t validator, void *validator_ctx)
	Durably sync, reopen read-only, and validate a POSIX stage.
static ra8_err_t	internal_parent_sync (fw_fs_posix_state_t *state, const char *path)
	Sync the destination's containing directory after publication.
static ra8_err_t	internal_txn_commit (void *ctx, void *transaction_state, bool *out_published)
	Atomically publish then durably sync the destination directory.
static ra8_err_t	internal_txn_abort (void *ctx, void *transaction_state)
	Close and remove a POSIX stage while preserving the destination.

Detailed Description

File-local contracts for the confined POSIX filesystem adapter.

Declares the adapter's file-local resolver, namespace, and transaction helpers so their complete contracts remain readable without forcing the implementation translation unit beyond the repository size ceiling. The cross-unit RA8_PRIV contracts live in fw_if_fs_posix_internal.h; this header remains private to fw_if_fs_posix.c, beside the byte-stream unit's corresponding file-local contracts.

Copyright

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

Since

Version 0.1.0

Definition in file fw_if_fs_posix_contracts_internal.h.

Function Documentation

internal_component_copy()

ra8_err_t internal_component_copy ( const char * start, uint16_t length, char * out )

static

Copy one bounded path component into a fixed local buffer.

Rejects empty or over-capacity names before copying exact bytes and appending a NUL for descriptor-relative system calls.

Parameters

[in]	start	First byte of the component in the portable path.
[in]	length	Component length in bytes.
[out]	out	Fixed k_posix_component_cap-byte destination.

Returns

Bounded copy status.

Return values

k_ra8_ok	The component and NUL were written.
k_ra8_err_invalid_size	Length is zero or exceeds the local capacity.

Precondition

start addresses at least length readable bytes.

out addresses k_posix_component_cap writable bytes.

Postcondition

Success writes one terminated component.

No byte outside the destination capacity is modified.

Note

Thread-safe for disjoint caller-owned buffers.

Since

Version 0.1.0

internal_directory_open()

ra8_err_t internal_directory_open ( fw_fs_posix_state_t * state, const char * path, int * out_fd )

static

Open a confined directory without following its final component.

Duplicates the bound root for /; otherwise resolves a no-follow parent, validates the leaf as a real directory, and opens it safely.

Parameters

[in,out]	state	Initialized confined-root adapter state.
[in]	path	Validated portable directory path.
[out]	out_fd	Receives an owned directory descriptor.

Returns

Resolution or directory-open status.

Return values

k_ra8_ok	out_fd owns an open directory descriptor.
k_ra8_err_access_denied	A traversed component is a symbolic link.
k_ra8_err_not_found	A component is absent or not a directory.
k_ra8_err_*	Mapped open or close failure.

Precondition

Pointer arguments are non-NULL and root_fd is live.

path passed portable lexical validation.

Postcondition

Success transfers exactly one descriptor to the caller.

Failure closes every descriptor acquired internally.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_intermediate_check()

ra8_err_t internal_intermediate_check ( int parent_fd, const char * component, posix_root_alias_t * out_alias )

static

Validate one directory component without following a symbolic link.

Uses no-follow metadata relative to an owned parent descriptor. Real directories are accepted without alias traversal. Linux denies every symbolic link. Darwin alone may publish a selection for an exact, verified filesystem-root tmp or var alias; every nested, absolute-target, or otherwise mismatched link remains denied.

Parameters

[in]	parent_fd	Open descriptor for the confined parent directory.
[in]	component	Terminated child component.
[out]	out_alias	Receives a verified alias selection or none.

Returns

Intermediate-component validation status.

Return values

k_ra8_ok	The component is a real directory or approved Darwin root alias.
k_ra8_err_access_denied	The component is an unapproved symbolic link.
k_ra8_err_not_found	The component is not a directory.
k_ra8_err_*	Mapped metadata or readlinkat failure.

Precondition

parent_fd is open and owned by the resolver.

component and out_alias are non-NULL and component is validated.

Postcondition

No descriptor ownership or filesystem contents change.

Linux always publishes none; Darwin success publishes only a verified strategy.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_mkdir()

ra8_err_t internal_mkdir ( void * ctx, const char * path )

static

Create one confined directory with no implicit parent creation.

Resolves a no-follow parent and invokes mkdirat on the final leaf, preserving the first creation failure over descriptor-close status.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	path	Validated portable directory path.

Returns

Resolution, creation, or close status.

Return values

k_ra8_ok	The directory was created and parent descriptor closed.
k_ra8_err_*	Mapped parent, mkdirat, or close failure.

Precondition

path is non-root and its parent already exists.

ctx owns a live confined root descriptor.

Postcondition

Success creates exactly one directory with fixed repository mode.

No component outside the bound root is accessed.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_native_stat()

ra8_err_t internal_native_stat ( fw_fs_posix_state_t * state, const char * path, struct stat * out, bool * out_exists )

static

Query native metadata without following the final component.

Handles the bound root directly; other paths resolve a confined parent and use fstatat(AT_SYMLINK_NOFOLLOW), mapping absence to data.

Parameters

[in,out]	state	Initialized confined-root adapter state.
[in]	path	Validated portable path.
[out]	out	Receives native metadata when the entry exists.
[out]	out_exists	Receives whether the entry exists.

Returns

Resolution or metadata-query status.

Return values

k_ra8_ok	Existence was determined, including a clean miss.
k_ra8_err_*	Mapped resolution, stat, or descriptor-close failure.

Precondition

Pointer arguments are non-NULL and state owns an open root descriptor.

path passed public portable validation.

Postcondition

Success always initializes out_exists.

A missing entry is success with out_exists false.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_next_component()

ra8_err_t internal_next_component ( const char ** cursor, char * out_name, uint16_t * out_length )

static

Scan and copy the next slash-delimited component of a cursor.

Bounds the scan to k_posix_component_cap, then copies the scanned span through internal_component_copy; the cursor itself is left unmoved so the caller can inspect the byte immediately after the scanned span before advancing.

Parameters

[in]	cursor	Address of the current scan position in the path.
[out]	out_name	Fixed k_posix_component_cap-byte destination.
[out]	out_length	Receives the scanned component's byte length.

Returns

Bounded scan-and-copy status.

Return values

k_ra8_ok	The component was scanned and copied.
k_ra8_err_invalid_size	The scan or the copy exceeded local capacity.

Precondition

*cursor addresses a NUL- or slash-terminated path remainder.

out_name addresses k_posix_component_cap writable bytes.

Postcondition

Success writes one terminated component and its length.

*cursor is unchanged; the caller advances it explicitly.

Note

Thread-safe for disjoint caller-owned buffers.

Since

Version 0.1.0

internal_node_type()

fw_fs_node_type_t internal_node_type ( mode_t mode )

static

Convert a POSIX mode into a portable node kind.

Recognizes regular files, directories, and symbolic links explicitly; every remaining host object is reported as portable other.

Parameters

[in]

mode

POSIX st_mode value.

Returns

Corresponding portable node type.

Return values

k_fw_fs_node_file	mode describes a regular file.
k_fw_fs_node_directory	mode describes a directory.
k_fw_fs_node_symlink	mode describes a symbolic link.
k_fw_fs_node_other	mode describes another host object.

Precondition

mode was obtained from a successful POSIX metadata query.

Standard S_IS* macros are available for the host ABI.

Postcondition

No memory or filesystem state is modified.

The result depends only on mode.

Note

Pure and thread-safe.

Since

Version 0.1.0

internal_parent_open_step()

ra8_err_t internal_parent_open_step ( int * current, const char * name )

static

Descend into one intermediate path component, retiring the old parent.

Opens a normal component no-follow, or on Darwin resolves an approved filesystem-root alias through its canonical no-follow path, then closes the descriptor owned on entry on every return path. Linux rejects every symbolic-link component before this descent.

Parameters

[in,out]	current	Owned parent descriptor on entry; replaced with the newly opened descriptor on success.
[in]	name	Terminated intermediate component name.

Returns

Descent status.

Return values

k_ra8_ok	current now owns the newly opened component directory.
other	Validation, open, or close failed; current is closed.

Precondition

current addresses an owned open directory descriptor.

name is a terminated component distinct from the final leaf.

Postcondition

The descriptor owned on entry is closed on every return path.

Success leaves exactly one owned descriptor in current.

Note

Not thread-safe for a shared descriptor.

Since

Version 0.1.0

internal_parent_sync()

ra8_err_t internal_parent_sync ( fw_fs_posix_state_t * state, const char * path )

static

Sync the destination's containing directory after publication.

Resolves the confined parent, requests directory durability, closes the descriptor, and preserves the fsync failure over close status.

Parameters

[in,out]	state	Initialized confined-root adapter state.
[in]	path	Validated published destination path.

Returns

Parent resolution, sync, or close status.

Return values

k_ra8_ok	Directory synchronization and close succeeded.
k_ra8_err_*	Mapped parent, fsync, or close failure.

Precondition

state owns a live root descriptor.

path names an already published entry.

Postcondition

Every acquired parent descriptor is closed.

Success makes the rename durable according to host guarantees.

Note

Thread-safe subject to host namespace and root lifecycle synchronization.

Since

Version 0.1.0

internal_rename()

ra8_err_t internal_rename ( void * ctx, const char * old_path, const char * new_path, bool replace )

static

Rename within the selected root without following either leaf.

No-follow stats both endpoints, rejects symlinks and cross-device parents, and selects replace or atomic no-replace host semantics.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	old_path	Validated existing source path.
[in]	new_path	Validated destination path.
[in]	replace	Whether an existing destination may be replaced atomically.

Returns

Validation, resolution, rename, or close status.

Return values

k_ra8_ok	The entry was renamed within one filesystem.
k_ra8_err_not_found	The source is absent.
k_ra8_err_access_denied	Either endpoint is a symbolic link.
k_ra8_err_invalid_arg	Parent directories are on different devices.
k_ra8_err_not_supported	Atomic no-replace is unavailable.
k_ra8_err_*	Mapped stat, resolution, rename, or close failure.

Precondition

Both paths passed public portable validation.

ctx owns a live confined root descriptor.

Postcondition

Success moves one entry with the requested replacement semantics.

Every acquired parent descriptor is closed.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_rename_noreplace()

ra8_err_t internal_rename_noreplace ( int old_fd, const char * old_leaf, int new_fd, const char * new_leaf )

static

Perform a host atomic no-replace rename without a TOCTOU fallback.

Uses Linux renameat2(RENAME_NOREPLACE) or Darwin renameatx_np(RENAME_EXCL) and fails closed on unsupported hosts.

Parameters

[in]	old_fd	Open source-parent descriptor.
[in]	old_leaf	Terminated source leaf.
[in]	new_fd	Open destination-parent descriptor.
[in]	new_leaf	Terminated destination leaf.

Returns

Atomic no-replace rename status.

Return values

k_ra8_ok	The source was atomically renamed to an absent destination.
k_ra8_err_not_supported	The host primitive is unavailable.
k_ra8_err_*	Mapped host rename failure.

Precondition

Both descriptors are open directories on one filesystem.

Both leaf names are validated and neither traversal nor symlinks are followed here.

Postcondition

Success moves the source without replacing a destination.

Unsupported hosts perform no filesystem mutation.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_rename_validate_endpoints()

ra8_err_t internal_rename_validate_endpoints ( fw_fs_posix_state_t * state, const char * old_path, const char * new_path )

static

Validate that a rename's source exists and neither endpoint is a symlink.

Stats both paths through the confined resolver and rejects an absent source or a present-but-symlinked source or destination before any parent descriptor is opened.

Parameters

[in]	state	Initialized confined-root adapter state.
[in]	old_path	Validated existing source path.
[in]	new_path	Validated destination path.

Returns

Endpoint validation status.

Return values

k_ra8_ok	The source exists and neither present endpoint is a symlink.
k_ra8_err_not_found	The source is absent.
k_ra8_err_access_denied	Either endpoint is a symbolic link.
k_ra8_err_*	Mapped metadata failure.

Precondition

Both paths passed public portable validation.

state owns a live confined root descriptor.

Postcondition

No descriptor is opened or closed by this check.

Neither endpoint's contents or metadata are modified.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_rmdir()

ra8_err_t internal_rmdir ( void * ctx, const char * path )

static

Remove one confined empty real directory.

No-follow stats the target before descriptor-relative AT_REMOVEDIR and rejects absent, symbolic-link, and non-directory targets.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	path	Validated portable directory path.

Returns

Validation, removal, or close status.

Return values

k_ra8_ok	The empty directory was removed.
k_ra8_err_not_found	The target is absent.
k_ra8_err_access_denied	The target is a symbolic link.
k_ra8_err_invalid_arg	The target is not a directory.
k_ra8_err_*	Mapped stat, resolution, removal, or close failure.

Precondition

ctx owns a live confined root descriptor.

The target is expected to be empty; recursive removal is unsupported.

Postcondition

Success removes exactly one empty real directory.

Symbolic links and non-directories are never removed.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_space()

ra8_err_t internal_space ( void * ctx, fw_fs_space_t * out )

static

Query confined-root volume byte totals with fstatvfs.

Multiplies block counts by the fragment size and distinguishes user- available free bytes from blocks reserved by the host filesystem.

Parameters

[in]	ctx	Initialized confined-root adapter context.
[out]	out	Portable total, free, and used byte snapshot.

Returns

Host space-query status.

Return values

k_ra8_ok	Every byte count was populated.
k_ra8_err_*	Mapped fstatvfs failure.

Precondition

ctx owns a live root descriptor.

out addresses one writable result object.

Postcondition

Success initializes all three portable byte counts.

Filesystem contents and descriptor position are unchanged.

Note

Thread-safe subject to root descriptor lifecycle synchronization.

Since

Version 0.1.0

internal_stage_open()

ra8_err_t internal_stage_open ( fw_fs_posix_state_t * state, posix_transaction_state_t * txn )

static

Create an exclusive sibling stage after bounded collision retries.

Advances the adapter transaction id, builds sibling names, and uses O_EXCL open so a race cannot silently replace an existing entry.

Parameters

[in,out]	state	Bound adapter state and transaction-id source.
[in,out]	txn	Transaction receiving stage path and writer descriptor.

Returns

Bounded stage-open status.

Return values

k_ra8_ok	A new exclusive stage is open and tracked.
k_ra8_err_no_mem	Every bounded candidate collided.
k_ra8_err_*	Naming or non-collision open failure.

Precondition

txn contains a validated terminated destination path.

Adapter root and transaction state remain live for all attempts.

Postcondition

Success sets writer_open and stage_exists.

At most k_posix_stage_attempts candidates are attempted.

Note

Not thread-safe; advances shared adapter transaction-id state.

Since

Version 0.1.0

internal_stat()

ra8_err_t internal_stat ( void * ctx, const char * path, fw_fs_stat_t * out )

static

Produce portable metadata for one path below the confined root.

Converts no-follow native metadata, timestamps, type, and size while normalizing directory size to zero and absence to node_none.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	path	Validated portable path.
[out]	out	Portable metadata destination.

Returns

Native stat or conversion status.

Return values

k_ra8_ok	out contains a complete existence snapshot.
k_ra8_err_*	Mapped confined metadata-query failure.

Precondition

Pointer arguments are non-NULL and ctx owns an open root descriptor.

out is writable and disjoint from adapter state.

Postcondition

Success fully initializes out.

Symbolic links are reported, never followed.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0

internal_txn_abort()

ra8_err_t internal_txn_abort ( void * ctx, void * transaction_state )

static

Close and remove a POSIX stage while preserving the destination.

Attempts every owned cleanup step, returns the first failure, and clears ownership flags only for resources actually released.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Transaction workspace to consume or retry.

Returns

First close or unlink failure, or success.

Return values

k_ra8_ok	Every owned stage resource was released.
k_ra8_err_*	First mapped close or unlink failure.

Precondition

transaction_state contains initialized ownership flags.

No concurrent operation uses the stage descriptor or path.

Postcondition

The destination is never modified.

Successfully released resources have ownership flags cleared.

Note

Not thread-safe for concurrent use of one transaction.

Since

Version 0.1.0

internal_txn_begin()

ra8_err_t internal_txn_begin ( void * ctx, void * transaction_state, uint32_t state_bytes, const char * destination, fw_fs_transaction_policy_t policy )

static

Begin a staged POSIX create-new or atomic-replacement transaction.

Validates workspace, host capability, and destination type/policy, copies the path, and opens a private exclusive sibling stage.

Parameters

[in,out]	ctx	Bound confined-root adapter context.
[out]	transaction_state	Caller workspace receiving transaction state.
[in]	state_bytes	Writable transaction workspace size.
[in]	destination	Validated portable destination path.
[in]	policy	Create-new or atomic-replace publication policy.

Returns

Transaction initialization status.

Return values

k_ra8_ok	A private stage is open for writing.
k_ra8_err_no_mem	Workspace is undersized or candidates are exhausted.
k_ra8_err_not_supported	Atomic no-replace is unavailable when required.
k_ra8_err_access_denied	Destination is a symbolic link.
k_ra8_err_invalid_arg	Destination is a directory.
k_ra8_err_exists	Create-new destination already exists.
k_ra8_err_*	Stat, copy, naming, or open failure.

Precondition

Pointer arguments and alignment satisfy the bound transaction contract.

Adapter root and host capability snapshot remain valid.

Postcondition

Success initializes an active unpublished stage.

Begin never creates or modifies the destination itself.

Note

Not thread-safe; uses adapter transaction-id and namespace state.

Since

Version 0.1.0

internal_txn_commit()

ra8_err_t internal_txn_commit ( void * ctx, void * transaction_state, bool * out_published )

static

Atomically publish then durably sync the destination directory.

Selects replace semantics from policy, renames the sibling stage, reports publication immediately, then fsyncs the containing directory.

Parameters

[in,out]	ctx	Bound confined-root adapter context.
[in,out]	transaction_state	Validated transaction workspace.
[out]	out_published	Receives publication truth independently of durability.

Returns

Transaction, rename, or directory-sync status.

Return values

k_ra8_ok	Publication and directory durability succeeded.
k_ra8_err_invalid_state	A stage writer remains open.
k_ra8_err_*	Rename or post-publication directory-sync failure.

Precondition

out_published is initialized false by public guarded dispatch.

Validation completed and the private stage exists.

Postcondition

Successful rename clears stage_exists and sets publication true.

A later sync failure still reports out_published true.

Note

Not thread-safe for concurrent transaction or namespace access.

Since

Version 0.1.0

internal_txn_seek()

ra8_err_t internal_txn_seek ( void * ctx, void * transaction_state, uint64_t offset )

static

Seek within the open POSIX stage for bounded header or table backfill.

Queries current stage length and rejects offsets beyond EOF before delegating an absolute seek.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Active transaction workspace.
[in]	offset	Absolute stage byte offset.

Returns

Transaction, size, or seek status.

Return values

k_ra8_ok	The stage position is offset.
k_ra8_err_invalid_state	The writer is not open.
k_ra8_err_invalid_size	offset exceeds current stage length.
k_ra8_err_*	Mapped size or seek failure.

Precondition

transaction_state contains an initialized transaction.

No concurrent stage I/O occurs.

Postcondition

Success changes only the stage position.

Stage length and destination contents are unchanged.

Note

Not thread-safe for concurrent use of one transaction.

Since

Version 0.1.0

internal_txn_validate()

ra8_err_t internal_txn_validate ( void * ctx, void * transaction_state, fw_fs_validate_fn_t validator, void * validator_ctx )

static

Durably sync, reopen read-only, and validate a POSIX stage.

Fsyncs and consumes the writer, reopens the private stage, invokes the injected portable validator, and closes the reader on every path.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Active transaction workspace.
[in]	validator	Read-only portable stage validator.
[in,out]	validator_ctx	Opaque validator context.

Returns

Sync, close, open, validation, or final-close status.

Return values

k_ra8_ok	Stage durability, validation, and cleanup succeeded.
k_ra8_err_invalid_state	The writer is not open.
k_ra8_err_*	First host or validator failure.

Precondition

Validator and transaction pointers satisfy the public contract.

The transaction owns one open private writer.

Postcondition

The transaction has no open writer or reader on return.

The stage remains private and abortable until commit.

Note

Not thread-safe for concurrent use of one transaction.

Since

Version 0.1.0

internal_txn_write()

ra8_err_t internal_txn_write ( void * ctx, void * transaction_state, const uint8_t * src, uint32_t len, uint32_t * out_written )

static

Append bytes to an open POSIX transaction stage.

Rejects a closed writer and otherwise reuses the complete-write stream adapter while preserving accepted-prefix error reporting.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Active transaction workspace.
[in]	src	Source bytes.
[in]	len	Exact byte count.
[out]	out_written	Accepted byte count.

Returns

Transaction or host write status.

Return values

k_ra8_ok	All len bytes were accepted.
k_ra8_err_invalid_state	The writer is not open.
k_ra8_err_*	Mapped stage write failure.

Precondition

Pointer and buffer arguments satisfy the public transaction contract.

src addresses len readable bytes when non-zero.

Postcondition

Success advances the stage position by len.

The destination remains unpublished and unchanged.

Note

Not thread-safe for concurrent use of one transaction.

Since

Version 0.1.0

internal_unlink()

ra8_err_t internal_unlink ( void * ctx, const char * path )

static

Remove one confined regular file while refusing directories and links.

No-follow stats the target before descriptor-relative unlink and rejects every target type except an existing regular file.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	path	Validated portable file path.

Returns

Validation, unlink, or close status.

Return values

k_ra8_ok	The regular file was removed.
k_ra8_err_not_found	The target is absent.
k_ra8_err_access_denied	The target is a symbolic link.
k_ra8_err_invalid_arg	The target is not a regular file.
k_ra8_err_*	Mapped stat, resolution, unlink, or close failure.

Precondition

ctx owns a live confined root descriptor.

path passed public portable validation.

Postcondition

Success removes exactly one regular-file directory entry.

Symbolic links and directories are never removed.

Note

Thread-safe subject to host namespace race semantics.

Since

Version 0.1.0