| 1 |
.TH LIBPSX 3 "2024-11-09" "" "Linux Programmer's Manual" |
| 2 |
.SH NAME |
| 3 |
psx_syscall3, psx_syscall6, psx_set_sensitivity \- POSIX semantics for system calls |
| 4 |
.SH SYNOPSIS |
| 5 |
.nf |
| 6 |
#include <sys/psx_syscall.h> |
| 7 |
|
| 8 |
long int psx_syscall3(long int syscall_nr, |
| 9 |
long int arg1, long int arg2, long int arg3); |
| 10 |
long int psx_syscall6(long int syscall_nr, |
| 11 |
long int arg1, long int arg2, long int arg3, |
| 12 |
long int arg4, long int arg5, long int arg6); |
| 13 |
int psx_set_sensitivity(psx_sensitivity_t sensitivity); |
| 14 |
void psx_load_syscalls(long int (**syscall_fn)(long int, |
| 15 |
long int, long int, long int), |
| 16 |
long int (**syscall6_fn)(long int, |
| 17 |
long int, long int, long int, |
| 18 |
long int, long int, long int)); |
| 19 |
.fi |
| 20 |
.sp |
| 21 |
Any code that uses one of the above functions can be linked as follows: |
| 22 |
.sp |
| 23 |
.I ld ... \-lpsx \-lpthread |
| 24 |
.sp |
| 25 |
.I gcc ... \-lpsx \-lpthread |
| 26 |
.sp |
| 27 |
Note, special flags are needed to get |
| 28 |
.B -lcap |
| 29 |
to operated with process wide capabilities when linked with |
| 30 |
.BR -lpsx . |
| 31 |
Namely, use the |
| 32 |
.B pkg-config |
| 33 |
option file: |
| 34 |
.B gcc ... \-lcap $(pkg-config \-\-libs \-\-cflags libpsx) |
| 35 |
More details are available in the |
| 36 |
.BR cap_get_proc (3) |
| 37 |
man page. |
| 38 |
.SH DESCRIPTION |
| 39 |
The |
| 40 |
.B libpsx |
| 41 |
library attempts to fill a gap left by the |
| 42 |
.BR pthreads (7) |
| 43 |
implementation on Linux. To be compliant POSIX threads, via the |
| 44 |
.BR nptl "(7) " setxid |
| 45 |
mechanism, glibc maintains consistent UID and GID credentials amongst |
| 46 |
all of the threads associated with the current process. However, other |
| 47 |
credential state is not supported by this abstraction. To support |
| 48 |
these extended kernel managed security attributes, |
| 49 |
.B libpsx |
| 50 |
provides a more generic pair of wrapping system call functions: |
| 51 |
.BR psx_syscall3 "() and " psx_syscall6 (). |
| 52 |
Like the |
| 53 |
.B setxid |
| 54 |
mechanism, the coordination of thread state is mediated by a realtime |
| 55 |
signal. Whereas the |
| 56 |
.B nptl:setxid |
| 57 |
mechanism uses signo=33 (which is hidden by glibc below a redefined |
| 58 |
.BR SIGRTMIN "), " libpsx |
| 59 |
inserts itself in the |
| 60 |
.B SIGSYS |
| 61 |
handler stack. It goes to great length to be the first such handler |
| 62 |
but acts as a pass-through for other |
| 63 |
.B SIGSYS |
| 64 |
uses. |
| 65 |
.PP |
| 66 |
An inefficient macrology trick supports the |
| 67 |
.BR psx_syscall () |
| 68 |
pseudo function which takes 1 to 7 arguments, depending on the needs |
| 69 |
of the caller. The macrology (which ultimately invokes |
| 70 |
.BR __psx_syscall ()) |
| 71 |
pads out the call to actually use |
| 72 |
.BR psx_syscall3 () |
| 73 |
or |
| 74 |
.BR psx_syscall6 () |
| 75 |
with zeros filling the missing arguments. While using this in source |
| 76 |
code will make it appear clean, the actual code footprint is |
| 77 |
larger. You are encouraged to use the more explicit |
| 78 |
.BR psx_syscall3 () |
| 79 |
and |
| 80 |
.BR psx_syscall6 () |
| 81 |
functions as needed. |
| 82 |
.PP |
| 83 |
.BR psx_set_sensitivity () |
| 84 |
changes the behavior of the mirrored system calls: |
| 85 |
.B PSX_IGNORE |
| 86 |
ensures that differences are ignored (the default behavior); |
| 87 |
.B PSX_WARNING |
| 88 |
prints a stderr notification about how the results differ; and |
| 89 |
.B PSX_ERROR |
| 90 |
prints the error details and generates a |
| 91 |
.B SIGSYS |
| 92 |
signal. |
| 93 |
.PP |
| 94 |
.BR psx_load_syscalls () |
| 95 |
can be used to set caller defined function pointers for invoking 3 and |
| 96 |
6 argument syscalls. This function can be used to configure a library, |
| 97 |
or program to change behavior when linked against |
| 98 |
.BR libpsx . |
| 99 |
Indeed, |
| 100 |
.B libcap |
| 101 |
uses this function from |
| 102 |
.B libpsx |
| 103 |
to override its thread scoped default system call based API. When |
| 104 |
linked with |
| 105 |
.BR libpsx ", " libcap |
| 106 |
can operate on all the threads of a multithreaded program to operate |
| 107 |
with POSIX semantics. |
| 108 |
.SH RETURN VALUE |
| 109 |
The return value for system call functions is generally the value |
| 110 |
returned by the kernel, or \-1 in the case of an error. In such cases |
| 111 |
.BR errno (3) |
| 112 |
is set to the detailed error value. The |
| 113 |
.BR psx_syscall3 "() and " psx_syscall6 () |
| 114 |
functions attempt a single threaded system call and return immediately |
| 115 |
in the case of an error. Should this call succeed, then the same |
| 116 |
system calls are executed from a signal handler on each of the other |
| 117 |
threads of the process. |
| 118 |
.SH CONFORMING TO |
| 119 |
The needs of |
| 120 |
.BR libcap (3) |
| 121 |
for POSIX semantics of capability manipulation. You can read more |
| 122 |
about why this is needed here: |
| 123 |
.sp |
| 124 |
https://sites.google.com/site/fullycapable/who-ordered-libpsx |
| 125 |
.sp |
| 126 |
Versions of |
| 127 |
.B libpsx |
| 128 |
prior to 2.72 only supported pthreads. Since libpsx-2.72 the library |
| 129 |
works with all Linux thread implementations as it operates at the |
| 130 |
lowest level of thread abstraction, LWPs. |
| 131 |
.SH "REPORTING BUGS" |
| 132 |
The |
| 133 |
.B libpsx |
| 134 |
library is distributed from |
| 135 |
https://sites.google.com/site/fullycapable/ where the release notes |
| 136 |
may already cover recent issues. Please report newly discovered bugs |
| 137 |
via: |
| 138 |
.TP |
| 139 |
https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757 |
| 140 |
.SH SEE ALSO |
| 141 |
.BR libcap (3), |
| 142 |
.BR cap_get_proc (3), |
| 143 |
.BR pthreads "(7) and" |
| 144 |
.BR nptl (7). |