sapi_safety_violation.h File Reference

Opt-in notification hook for the three new safety primitives (safe pointer, checked integer arithmetic, bounds check): a SEPARATE, dedicated handler from sapi_safestate_handler_t (sapi_safestate.h) - registering it does not change any of those primitives' own return-code contract (REQ-COMMON-CAST-004/ 005, REQ-OAL-SAFEPTR-001/002) in any way; with no handler registered (the default), nothing about their behavior changes at all. More...

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

Include dependency graph for sapi_safety_violation.h:

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

Go to the source code of this file.

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 notification hook for the three new safety primitives (safe pointer, checked integer arithmetic, bounds check): a SEPARATE, dedicated handler from sapi_safestate_handler_t (sapi_safestate.h) - registering it does not change any of those primitives' own return-code contract (REQ-COMMON-CAST-004/ 005, REQ-OAL-SAFEPTR-001/002) in any way; with no handler registered (the default), nothing about their behavior changes at all.

Why a separate mechanism from sapi_safestate: unlike a checkpoint timeout or a voter disagreement (which are ALWAYS genuine faults, so REQ-CHECKPOINT-003/REQ-VOTER-005 escalate through sapi_safestate_enter() unconditionally), these three primitives are also called during ordinary, expected control flow (e.g. sapi_cast_bounds_check() used to ask "is this the last valid index" is not a fault). Forcing every one of their failures through sapi_safestate_enter() would trigger a permanent halt (REQ-COMMON-SAFESTATE-002) on entirely normal code paths. This module instead gives an integrator who WANTS visibility into every such event (e.g. to log it, count it, or make their OWN judgment call about escalating) an explicit, separate opt-in - they decide what a violation means for their own application, this module does not decide for them.

Note

The file/line reported is the DETECTION site inside this framework's own implementation (sapi_safe_ptr.c/sapi_cast.c), not the ultimate caller's call site - unlike SAPI_ASSERT/ SAPI_SAFESTATE (macros, so they capture the caller's own FILE/__LINE__), the three primitives this module instruments are ordinary functions, not macros, per sapi_cast.h's own 72-function convention. The violation kind and message (which does include the specific values involved) are the primary diagnostic content; the file/line narrows down which primitive detected it, not where it was called from.

REQ-COMMON-SAFETYVIOLATION-001: no dynamic allocation; a single fixed handler slot (this is a lower-frequency, broader-scope hook than sapi_safestate's own per-level slots - one registered handler covers all three primitive families). REQ-COMMON-SAFETYVIOLATION-002: with no handler registered, sapi_safety_violation_report() is a no-op - reporting a violation never itself becomes a new failure mode.

Definition in file sapi_safety_violation.h.