Safe Pointer Wrapper

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

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

Data Structures
struct	sapi_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
sapi_status_t	sapi_safe_ptr_init (sapi_safe_ptr_t *sp, void *ptr, size_t size)
	Initializes sp to wrap [ptr, ptr + size), writing the canary.
bool	sapi_safe_ptr_is_valid (const sapi_safe_ptr_t *sp)
	Checks whether sp currently wraps a valid, non-invalidated region.
sapi_status_t	sapi_safe_ptr_get (const sapi_safe_ptr_t *sp, void **out_ptr)
	Retrieves the wrapped pointer directly (the whole region, no offset) after validating it.
sapi_status_t	sapi_safe_ptr_offset (const sapi_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	sapi_safe_ptr_invalidate (sapi_safe_ptr_t *sp)
	Invalidates sp: clears the wrapped pointer and the canary, so every subsequent access on sp fails SAPI_STATUS_DATA_CORRUPTION.

Detailed Description

Bounds + NULL + corruption-canary checked pointer access.

Function Documentation

sapi_safe_ptr_init()

sapi_status_t sapi_safe_ptr_init	(	sapi_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 SAPI_STATUS_INVALID_PARAM, not SAPI_STATUS_DATA_CORRUPTION, since the canary is still written correctly).
size	Size in bytes of the region ptr points to.

Returns

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

Definition at line 17 of file sapi_safe_ptr.c.

sapi_safe_ptr_is_valid()

bool sapi_safe_ptr_is_valid

(

const sapi_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 sapi_safe_ptr.c.

sapi_safe_ptr_get()

sapi_status_t sapi_safe_ptr_get	(	const sapi_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

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if sp or out_ptr is NULL; SAPI_STATUS_DATA_CORRUPTION if sp's canary is wrong (REQ-OAL-SAFEPTR-001).

Definition at line 46 of file sapi_safe_ptr.c.

sapi_safe_ptr_offset()

sapi_status_t sapi_safe_ptr_offset	(	const sapi_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

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if sp or out_ptr is NULL; SAPI_STATUS_DATA_CORRUPTION if sp's canary is wrong (REQ-OAL-SAFEPTR-001); SAPI_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 sapi_safe_ptr.c.

sapi_safe_ptr_invalidate()

void sapi_safe_ptr_invalidate

(

sapi_safe_ptr_t *

sp

)

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

Relevant when the underlying region is logically released back to a pool (sapi_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 sapi_safe_ptr.c.