sapi_safe_ptr.h File Reference

Safe-pointer wrapper: bounds + NULL + corruption-canary checked access to a raw memory region, so callers never perform raw pointer arithmetic on a buffer directly. More...

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_safe_ptr.h:

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

Go to the source code of this file.

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

Safe-pointer wrapper: bounds + NULL + corruption-canary checked access to a raw memory region, so callers never perform raw pointer arithmetic on a buffer directly.

Wraps a {pointer, size} pair plus a canary written at init time and verified on every access - defense-in-depth against a caller passing an uninitialized or corrupted wrapper (e.g. a bit-flip in a statically allocated struct), the same posture sapi_checksum.c's own init-state check already uses for its internal manager state. No dynamic allocation: sapi_safe_ptr_t wraps memory the caller already owns (a static buffer, a pool block from sapi_memory.h, a stack buffer whose lifetime outlives the wrapper's use), it never allocates anything itself.

REQ-OAL-SAFEPTR-001: every access function shall verify the canary first; a corrupted wrapper yields SAPI_STATUS_DATA_CORRUPTION before any other check runs. REQ-OAL-SAFEPTR-002: sapi_safe_ptr_offset() shall verify offset + length <= size before computing the resulting pointer - restricted pointer arithmetic, never raw ptr + offset at the call site (MISRA C:2012 rules 18.1/18.4). REQ-OAL-SAFEPTR-003: sapi_safe_ptr_invalidate() shall clear both the wrapped pointer and the canary, so a subsequent access on the same wrapper fails SAPI_STATUS_DATA_CORRUPTION rather than silently succeeding against a logically-freed region.

Definition in file sapi_safe_ptr.h.