Safety Primitive Violation Notification

Opt-in handler for safe-pointer/checked-cast/bounds-check violations. More...

Files
file	src/utils/safestate/sapi_safety_violation.c
	See sapi_safety_violation.h for behavior.

Typedefs
typedef void(*)	sapi_safety_violation_handler_t(sapi_safety_violation_kind_t kind, const char *file, int32_t line, const char *message)
	Handler invoked by sapi_safety_violation_report().

Enumerations
enum	sapi_safety_violation_kind_t { SAPI_SAFETY_VIOLATION_CORRUPTION = 0 , SAPI_SAFETY_VIOLATION_OVERFLOW = 1 , SAPI_SAFETY_VIOLATION_OUT_OF_RANGE = 2 }
	Which safety primitive detected the violation. More...

Functions
sapi_status_t	sapi_safety_violation_register_handler (sapi_safety_violation_handler_t handler)
	Registers the single handler invoked by sapi_safety_violation_report(). Registering again replaces the previous handler (same convention as sapi_safestate_register_handler()).
void	sapi_safety_violation_report (sapi_safety_violation_kind_t kind, const char *file, int32_t line, const char *message)
	Reports one violation to the registered handler, if any.

Detailed Description

Opt-in handler for safe-pointer/checked-cast/bounds-check violations.

Typedef Documentation

sapi_safety_violation_handler_t

typedef void(*) sapi_safety_violation_handler_t(sapi_safety_violation_kind_t kind, const char *file, int32_t line, const char *message)

Handler invoked by sapi_safety_violation_report().

Parameters

kind	Which kind of violation was detected.
file	Detection site file (see this header's own

Note

on why this is the primitive's own file, not the caller's), may be NULL.

Parameters

line	Detection site line.
message	Human-readable detail (typically includes the actual values involved), may be NULL.

Note

Unlike sapi_safestate_handler_t, this handler is expected to return - it is a notification, not a fault-reaction level. Do not call sapi_safestate_enter() unconditionally from inside it; that would defeat the whole point of keeping this separate from sapi_safestate (see this header's own file-level doc) - make that decision deliberately, in your own handler, if that is what your application wants for a specific kind.

Definition at line 99 of file sapi_safety_violation.h.

Enumeration Type Documentation

sapi_safety_violation_kind_t

enum sapi_safety_violation_kind_t

Which safety primitive detected the violation.

Enumerator
SAPI_SAFETY_VIOLATION_CORRUPTION	sapi_safe_ptr_get()/_offset() found a corrupted canary (REQ-OAL-SAFEPTR-001) - never a normal condition.
SAPI_SAFETY_VIOLATION_OVERFLOW	A sapi_cast_checked_add_*()/_sub_*()/_mul_*() call detected overflow or underflow (REQ-COMMON-CAST-004).
SAPI_SAFETY_VIOLATION_OUT_OF_RANGE	sapi_cast_bounds_check() (REQ-COMMON-CAST-005) or sapi_safe_ptr_offset()'s own bounds check (REQ-OAL-SAFEPTR-002) found index/offset+length outside the valid range.

Definition at line 65 of file sapi_safety_violation.h.

Function Documentation

sapi_safety_violation_register_handler()

sapi_status_t sapi_safety_violation_register_handler

(

sapi_safety_violation_handler_t

handler

)

Registers the single handler invoked by sapi_safety_violation_report(). Registering again replaces the previous handler (same convention as sapi_safestate_register_handler()).

Parameters

handler

Handler to invoke on every reported violation. Must not be NULL - pass a handler that does nothing if you want to temporarily stop reacting without un-instrumenting the primitives themselves (there is no "unregister").

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if handler is NULL.

Definition at line 10 of file sapi_safety_violation.c.

sapi_safety_violation_report()

void sapi_safety_violation_report	(	sapi_safety_violation_kind_t	kind,
		const char *	file,
		int32_t	line,
		const char *	message )

Reports one violation to the registered handler, if any.

Called internally by sapi_safe_ptr_get()/_offset() and the sapi_cast_checked_*()/sapi_cast_bounds_check() functions at their own detection points - not normally called directly by application code.

Parameters

kind	Which kind of violation occurred.
file	Detection site file, may be NULL.
line	Detection site line.
message	Human-readable detail, may be NULL.

Safety:

No-op (REQ-COMMON-SAFETYVIOLATION-002) if no handler is registered - reporting a violation can never itself introduce a new failure mode.

Definition at line 20 of file sapi_safety_violation.c.