Document scram(2).

libc/Makefile

@@ -751,6 +751,9 @@ crtn.o \
 MISCOBJ=\
 $(CRTOBJ) \
 
+MANPAGES2=\
+scram/scram.2
+
 HEADERS:=$(shell find include -type f)
 
 LIBK_OBJS:=$(FREEOBJS:.o=.libk.o)
@@ -774,7 +777,7 @@ libs: $(BINS)
 libs-kernel: $(BINSKERNEL)
 
 .PHONY: all libs headers clean install install-include-dirs install-headers \
-        install-lib-dirs install-libs libs-kernel
+        install-lib-dirs install-libs install-man libs-kernel
 
 FORCE:
 
@@ -834,7 +837,7 @@ clean:
 	rm -f *.o */*.o */*/*.o *.a
 
 # Installation into sysroot
-install: install-headers install-libs install-libs-kernel
+install: install-headers install-libs install-libs-kernel install-man
 
 $(DESTDIR)$(LIBDIR):
 	mkdir -p $@
@@ -857,3 +860,7 @@ install-lib-dirs: $(DESTDIR)$(LIBDIR)
 install-libs: $(INSTALLLIBS)
 
 install-libs-kernel: $(INSTALLLIBSKERNEL)
+
+install-man:
+	mkdir -p $(DESTDIR)$(MANDIR)/man2
+	cp $(MANPAGES2) $(DESTDIR)$(MANDIR)/man2

libc/scram/scram.2

@@ -0,0 +1,113 @@
+.Dd February 8, 2017
+.Dt SCRAM 2
+.Os
+.Sh NAME
+.Nm scram
+.Nd emergency process shutdown
+.Sh SYNOPSIS
+.In scram.h
+.Ft void
+.Fn scram "int event" "const void *info"
+.Sh DESCRIPTION
+.Fn 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.
+.Pp
+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
+.Fn scram
+to terminate the process immediately.
+The kernel will use the provided event information to write a formatted error
+message to the kernel log.
+.Pp
+.Fa event
+specifies which kind of event occurred and can be one of:
+.Pp
+.Bl -tag -width "SCRAM_UNDEFINED_BEHAVIOR" -compact -offset indent
+.It SCRAM_ASSERT
+Assertion failure.
+.It SCRAM_STACK_SMASH
+Stack smash.
+.It SCRAM_UNDEFINED_BEHAVIOR
+Undefined behavior.
+.El
+.Pp
+.Fa info
+points to the appropriate structure containing further information on the event
+or
+.Dv NULL
+if there is no information available:
+.Bd -literal
+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 */
+};
+.Ed
+.Sh RETURN VALUES
+The
+.Fn scram
+function never returns as the process is unconditionally terminated.
+.Sh ERRORS
+.Fn 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.
+.Sh NOTES
+.Fn 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
+.Xr assert 3 ,
+the stack protector
+.Xr ( gcc 1
+.Fl fstack-protector ) ,
+and the undefined behavior sanitizer
+.Xr ( gcc 1
+.Fl fsanitize=undefined ) .
+The design of
+.Fn 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.
+.Pp
+The
+.Fn 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
+.Fn scram .
+It is always safe and desirable to use these features in production on Sortix.
+.Sh SEE ALSO
+.Xr gcc 1 ,
+.Xr _exit 2 ,
+.Xr exit_thread 2 ,
+.Xr assert 3 ,
+.Xr exit 3
+.Sh HISTORY
+The
+.Fn scram
+system call originally appeared in Sortix 1.0.