Sortix volatile manual
This manual documents Sortix volatile, a development build that has not been officially released. You can instead view this document in the latest official manual.
SCRAM(2) | System Calls Manual | SCRAM(2) |
NAME
scram
— emergency
process shutdown
SYNOPSIS
#include
<scram.h>
void
scram
(int
event, const void
*info);
DESCRIPTION
scram
()
unconditionally terminates the process abnormally due to the specified
event. It is designed for use when the process has potentially been
compromised and therefore can’t possibly continue safely. Its use
does not necessarily mean the process was compromised, but it does imply a
bug was detected.
The event information structures are designed to be
trivially to filled in during an emergency with the information that is
readily available. If the process has potentially been compromised, the
calling function should not do any formatting of debug information or
perform memory allocations, but just use existing values or constants as the
event information and call
scram
() to
terminate the process immediately. The kernel will use the provided event
information to write a formatted error message to the kernel log.
event specifies which kind of event occurred and can be one of:
- SCRAM_ASSERT
- Assertion failure.
- SCRAM_STACK_SMASH
- Stack smash.
- SCRAM_UNDEFINED_BEHAVIOR
- Undefined behavior.
info points to the appropriate structure
containing further information on the event or NULL
if there is no information available:
struct scram_assert { /* SCRAM_ASSERT */ const char *filename; /* file the assertion failed in */ unsigned long line; /* line the assertion failed on */ const char *function; /* function containing the assertion */ const char *expression; /* assertion expression */ }; /* SCRAM_STACK_SMASH has no information structure */ struct scram_undefined_behavior { /* SCRAM_UNDEFINED_BEHAVIOR */ const char *filename; /* file with undefined behavior */ unsigned long line; /* line with undefined behavior */ unsigned long column; /* column on the line with undefined behavior */ const char *violation; /* description of the undefined behavior */ };
RETURN VALUES
The scram
() function never returns as the
process is unconditionally terminated.
ERRORS
scram
() never fails as the process is
always terminated, even on invalid parameters. The kernel may fail to
allocate copies of strings, in which case "<unknown>" is
used as a replacement in the error message.
NOTES
scram
()
is generally not meant to be used directly by application developers, but is
for internal use by the standard library in the implementation of
assert(3), the stack
protector (gcc(1)
-fstack-protector
), and the undefined behavior
sanitizer (gcc(1)
-fsanitize=undefined
). The design of
scram
() is motivated by gcc's upstream libssp and
libubsan libraries, which attempt to print debug information prior to
terminating the process abnormally. Doing so is a risk, as the process may
have been compromised and basic things like stdio cannot be trusted as
crucial pointers and state may have been overwritten, and memory allocations
are dangerous because the heap might be damaged. Attempting to format debug
information may ironically give the attacker another chance to subvert
control flow. The gcc upstream libubsan library is designed for debugging
and should not go anywhere near production.
The
scram
()
function avoids all these issues by design by having the kernel print the
debug information. Sortix uses neither gcc library and the standard library
has its own secure implementations using scram
(). It
is always safe and desirable to use these features in production on
Sortix.
SEE ALSO
HISTORY
The scram
() system call originally
appeared in Sortix 1.0.
February 8, 2017 | Sortix 1.1.0-dev |