diff options
Diffstat (limited to 'doc/libpsx.3')
| -rw-r--r-- | doc/libpsx.3 | 59 |
1 files changed, 49 insertions, 10 deletions
diff --git a/doc/libpsx.3 b/doc/libpsx.3 index 4ba306b..4a0b5b6 100644 --- a/doc/libpsx.3 +++ b/doc/libpsx.3 @@ -1,12 +1,21 @@ -.TH LIBPSX 3 "2021-03-06" "" "Linux Programmer's Manual" +.TH LIBPSX 3 "2021-12-12" "" "Linux Programmer's Manual" .SH NAME -psx_syscall3, psx_syscall6 \- POSIX semantics for system calls +psx_syscall3, psx_syscall6, psx_set_sensitivity \- POSIX semantics for system calls .SH SYNOPSIS .nf #include <sys/psx_syscall.h> -long int psx_syscall3(long int syscall_nr, long int arg1, long int arg2, long int arg3); -long int psx_syscall6(long int syscall_nr, long int arg1, long int arg2, long int arg3, long int arg4, long int arg5, long int arg6); +long int psx_syscall3(long int syscall_nr, + long int arg1, long int arg2, long int arg3); +long int psx_syscall6(long int syscall_nr, + long int arg1, long int arg2, long int arg3, + long int arg4, long int arg5, long int arg6); +int psx_set_sensitivity(psx_sensitivity_t sensitivity); +void psx_load_syscalls(long int (**syscall_fn)(long int, + long int, long int, long int), + long int (**syscall6_fn)(long int, + long int, long int, long int, + long int, long int, long int)); .fi .sp Link with one of these: @@ -21,7 +30,7 @@ library attempts to fill a gap left by the .BR pthreads (7) implementation on Linux. To be compliant POSIX threads, via the .BR nptl "(7) " setxid -mechanism glibc maintains consistent UID and GID credentials amongst +mechanism, glibc maintains consistent UID and GID credentials amongst all of the threads associated with the current process. However, other credential state is not supported by this abstraction. To support these extended kernel managed security attributes, @@ -34,10 +43,12 @@ mechanism, the coordination of thread state is mediated by a realtime signal. Whereas the .B nptl:setxid mechanism uses signo=33 (which is hidden by glibc below a redefined -SIGRTMIN), -.B libpsx -inserts itself in the SIGSYS handler stack. It goes to great length to -be the first such handler but acts as a pass-through for other SIGSYS +.BR SIGRTMIN "), " libpsx +inserts itself in the +.B SIGSYS +handler stack. It goes to great length to be the first such handler +but acts as a pass-through for other +.B SIGSYS uses. .PP A linker trick of @@ -51,7 +62,9 @@ can keep track of all pthreads. An inefficient macrology trick supports the .BR psx_syscall () pseudo function which takes 1 to 7 arguments, depending on the needs -of the caller. The macrology pads out the call to actually use +of the caller. The macrology (which ultimately invokes +.BR __psx_syscall ()) +pads out the call to actually use .BR psx_syscall3 () or .BR psx_syscall6 () @@ -62,6 +75,32 @@ larger. You are encouraged to use the more explicit and .BR psx_syscall6 () functions as needed. +.PP +.BR psx_set_sensitivity () +changes the behavior of the mirrored system calls: +.B PSX_IGNORE +ensures that differences are ignored (the default behavior); +.B PSX_WARNING +prints a stderr notification about how the results differ; and +.B PSX_ERROR +prints the error details and generates a +.B SIGSYS +signal. +.PP +.BR psx_load_syscalls () +can be used to set caller defined function pointers for invoking 3 and +6 argument syscalls. This function can be used to configure a library, +or program to change behavior when linked against +.BR libpsx . +Indeed, +.B libcap +uses this function from +.B libpsx +to override its thread scoped default system call based API. When +linked with +.BR libpsx ", " libcap +can operate on all the threads of a multithreaded program to operate +with POSIX semantics. .SH RETURN VALUE The return value for system call functions is generally the value returned by the kernel, or \-1 in the case of an error. In such cases |