emu_elf_source_internal.h File Reference

Private raw-descriptor ELF source operations. More...

#include <stddef.h>
#include <stdint.h>
#include "emu_elf.h"
#include "ra8_attributes.h"

Include dependency graph for emu_elf_source_internal.h:

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

Go to the source code of this file.

Functions
emu_elf_io_result_t	priv_emu_elf_source_open (const char *path, emu_elf_source_t *source)
	Open one regular ELF source without reading or allocating its bytes.
emu_elf_io_result_t	priv_emu_elf_source_close (emu_elf_source_t *source)
	Close and invalidate one independently owned ELF source.
emu_elf_io_result_t	priv_emu_elf_read (const emu_elf_source_t *source, uint64_t offset, size_t required_bytes, void *scratch, size_t supplied_bytes, emu_elf_view_t *view)
	Read one exact source range into caller-owned bounded scratch.

Detailed Description

Private raw-descriptor ELF source operations.

Shares the bounded source seam only among emulator engine and composition translation units; public ELF types remain in emu_elf.h.

Copyright

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

Since

0.1.0

Definition in file emu_elf_source_internal.h.

Function Documentation

priv_emu_elf_read()

emu_elf_io_result_t priv_emu_elf_read ( const emu_elf_source_t * source, uint64_t offset, size_t required_bytes, void * scratch, size_t supplied_bytes, emu_elf_view_t * view )

nodiscard

Read one exact source range into caller-owned bounded scratch.

Parameters

[in]	source	Open immutable ELF source.
[in]	offset	First source byte to read.
[in]	required_bytes	Exact requested byte count.
[out]	scratch	Caller-owned destination.
[in]	supplied_bytes	Available destination bytes.
[out]	view	Receives the complete transient view on success.

Returns

Exact range, capacity, or transfer status.

Return values

k_emu_elf_io_ok	The view was published completely.
k_emu_elf_io_capacity	Required bytes exceed supplied bytes.

Precondition

scratch spans supplied_bytes writable bytes when nonzero.

source remains open through the operation.

Postcondition

Failure leaves view untouched.

Success publishes exactly required_bytes at offset.

Note

Failure may alter scratch bytes but never publishes a partial view.

Since

0.1.0

Definition at line 99 of file emu_elf_source.c.

References emu_elf_source_t::fd, internal_elf_result(), internal_from_host(), k_emu_elf_io_capacity, k_emu_elf_io_eof, k_emu_elf_io_invalid, k_emu_elf_io_ok, k_emu_io_ok, emu_elf_source_t::length, priv_emu_io_pread_exact(), and emu_io_result_t::status.

Referenced by internal_div0_scan_segment(), internal_load_segment(), internal_long_shift_segment(), internal_program_table(), internal_stream_segment(), and internal_symbol_read().

priv_emu_elf_source_close()

emu_elf_io_result_t priv_emu_elf_source_close ( emu_elf_source_t * source )

nodiscard

Close and invalidate one independently owned ELF source.

Parameters

[in,out]

source

Open source to close.

Returns

Exact close status.

Return values

k_emu_elf_io_ok	The descriptor was closed and invalidated.
k_emu_elf_io_invalid	source was null or already closed.

Precondition

source is null, closed, or owned by the caller.

No concurrent read is active through source.

Postcondition

A valid descriptor is invalidated even when close reports error.

Other source instances remain usable.

Note

Not safe during a concurrent read through the same source.

Since

0.1.0

Definition at line 85 of file emu_elf_source.c.

References emu_elf_source_t::fd, internal_elf_result(), internal_from_host(), k_emu_elf_io_invalid, k_emu_elf_io_ok, k_emu_io_ok, emu_elf_source_t::length, priv_emu_io_close(), and emu_io_result_t::status.

Referenced by internal_main_load_images(), internal_main_load_ns(), internal_main_load_primary(), internal_main_run_loaded(), and priv_run_cleanup().

priv_emu_elf_source_open()

emu_elf_io_result_t priv_emu_elf_source_open ( const char * path, emu_elf_source_t * source )

nodiscard

Open one regular ELF source without reading or allocating its bytes.

Parameters

[in]	path	NUL-terminated source path.
[out]	source	Receives an independently owned descriptor on success.

Returns

Exact open result including the full source length.

Return values

k_emu_elf_io_ok	A regular source was published with its exact length.
k_emu_elf_io_error	The source could not be opened or stated.

Precondition

path and source are non-null.

source is not currently open.

Postcondition

Failure leaves source untouched and owns no descriptor.

Success leaves source open until priv_emu_elf_source_close.

Note

Distinct source objects have independent lifetimes.

Since

0.1.0

Definition at line 70 of file emu_elf_source.c.

References internal_elf_result(), internal_from_host(), k_emu_elf_io_invalid, k_emu_elf_io_ok, k_emu_io_ok, emu_elf_source_t::length, priv_emu_io_open_read(), and emu_io_result_t::status.

Referenced by internal_main_load_ns(), and internal_main_load_primary().