Safe Pointer Wrapper

Bounds + NULL + corruption-canary checked pointer access. More...

Files
file	src/oal/memory/rte_safe_ptr.c
	See rte_safe_ptr.h for behavior.

Data Structures
struct	rte_safe_ptr_t
	A bounds-checked, canary-protected wrapper around one raw memory region. Opaque to callers in spirit (every field is manipulated only through the functions below) but a plain struct, not a handle, so it can be embedded directly in a caller's own statically-allocated storage - no dynamic allocation, matching CLAUDE.md. More...

Functions
rte_status_t	rte_safe_ptr_init (rte_safe_ptr_t *sp, void *ptr, size_t size)
	Initializes sp to wrap [ptr, ptr + size), writing the canary.
bool	rte_safe_ptr_is_valid (const rte_safe_ptr_t *sp)
	Checks whether sp currently wraps a valid, non-invalidated region.
rte_status_t	rte_safe_ptr_get (const rte_safe_ptr_t *sp, void **out_ptr)
	Retrieves the wrapped pointer directly (the whole region, no offset) after validating it.
rte_status_t	rte_safe_ptr_offset (const rte_safe_ptr_t *sp, size_t offset, size_t length, void **out_ptr)
	Computes a bounds-checked pointer at offset within sp's region, verifying the caller's intended access of length bytes starting at offset stays within the wrapped region.
void	rte_safe_ptr_invalidate (rte_safe_ptr_t *sp)
	Invalidates sp: clears the wrapped pointer and the canary, so every subsequent access on sp fails RTE_STATUS_DATA_CORRUPTION.

Detailed Description

Bounds + NULL + corruption-canary checked pointer access.

Function Documentation

rte_safe_ptr_init()

rte_status_t rte_safe_ptr_init	(	rte_safe_ptr_t *	sp,
		void *	ptr,
		size_t	size )

Initializes sp to wrap [ptr, ptr + size), writing the canary.

Parameters

sp	Wrapper to initialize. Must not be NULL.
ptr	Region to wrap. May be NULL only if size is 0 (an intentionally empty wrapper - every access function then fails RTE_STATUS_INVALID_PARAM, not RTE_STATUS_DATA_CORRUPTION, since the canary is still written correctly).
size	Size in bytes of the region ptr points to.

Returns

RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM if sp is NULL, or ptr is NULL while size is non-zero.

Definition at line 17 of file rte_safe_ptr.c.

rte_safe_ptr_is_valid()

bool rte_safe_ptr_is_valid

(

const rte_safe_ptr_t *

sp

)

Checks whether sp currently wraps a valid, non-invalidated region.

Parameters

sp	Wrapper to check. Must not be NULL.

Returns

true if sp's canary is intact and its wrapped pointer is non-NULL; false otherwise (including sp itself being NULL).

Definition at line 33 of file rte_safe_ptr.c.

rte_safe_ptr_get()

rte_status_t rte_safe_ptr_get	(	const rte_safe_ptr_t *	sp,
		void **	out_ptr )

Retrieves the wrapped pointer directly (the whole region, no offset) after validating it.

Parameters

sp	Wrapper to read. Must not be NULL.
out_ptr	Receives sp's wrapped pointer on success; left untouched on failure. Must not be NULL.

Returns

RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM if sp or out_ptr is NULL; RTE_STATUS_DATA_CORRUPTION if sp's canary is wrong (REQ-OAL-SAFEPTR-001).

Definition at line 46 of file rte_safe_ptr.c.

rte_safe_ptr_offset()

rte_status_t rte_safe_ptr_offset	(	const rte_safe_ptr_t *	sp,
		size_t	offset,
		size_t	length,
		void **	out_ptr )

Computes a bounds-checked pointer at offset within sp's region, verifying the caller's intended access of length bytes starting at offset stays within the wrapped region.

Parameters

sp	Wrapper to read. Must not be NULL.
offset	Byte offset from the start of sp's region.
length	Number of bytes the caller intends to access starting at offset.
out_ptr	Receives (uint8_t *)sp->ptr + offset on success; left untouched on failure. Must not be NULL.

Returns

RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM if sp or out_ptr is NULL; RTE_STATUS_DATA_CORRUPTION if sp's canary is wrong (REQ-OAL-SAFEPTR-001); RTE_STATUS_VALUE_OUT_OF_RANGE if offset + length > sp->size, including the case where offset + length itself would overflow size_t (REQ-OAL-SAFEPTR-002).

Definition at line 66 of file rte_safe_ptr.c.

rte_safe_ptr_invalidate()

void rte_safe_ptr_invalidate

(

rte_safe_ptr_t *

sp

)

Invalidates sp: clears the wrapped pointer and the canary, so every subsequent access on sp fails RTE_STATUS_DATA_CORRUPTION.

Relevant when the underlying region is logically released back to a pool (rte_mem_pool_release()) or otherwise stops being valid for this wrapper to describe, while sp itself (the struct) persists (e.g. a reusable static wrapper) - no dynamic allocation is involved on either side of this call.

Parameters

sp	Wrapper to invalidate. NULL is a documented no-op.

Definition at line 105 of file rte_safe_ptr.c.