Debian Codegraph @

doc/libpsx.3

raw
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).