Debian Codegraph @

psx/doc.go

raw
1 // Package psx provides support for system calls that are run
2 // simultaneously on all threads under Linux. It supports tool chains
3 // after go1.16. Earlier toolchains had no reliable way to support
4 // this because of [Bug 219478].
5 //
6 // The package works differently depending on whether or not
7 // CGO_ENABLED is 0 or 1.
8 //
9 // In the former case, psx is a low overhead wrapper for the two
10 // native go calls: syscall.AllThreadsSyscall() and
11 // syscall.AllThreadsSyscall6() introduced in go1.16. We provide this
12 // package wrapping to minimize client source code changes when
13 // compiling with or without CGo enabled.
14 //
15 // In the latter case it works via CGo wrappers for system call
16 // functions that call the C [lib]psx functions of these names. This
17 // ensures that the system calls execute simultaneously on all the
18 // threads of the Go (and CGo) combined runtime.
19 //
20 // With CGo, the psx support works in the following way: the thread
21 // that is first asked to execute the syscall does so, and determines
22 // if it succeeds or fails. If it fails, it returns immediately
23 // without attempting the syscall on other threads. If the initial
24 // attempt succeeds, however, then the runtime is stopped in order for
25 // the same system call to be performed on all the remaining threads
26 // of the runtime. Once all threads have completed the syscall, the
27 // return codes are those obtained by the first thread's invocation
28 // of the syscall.
29 //
30 // Note, there is no need to use this variant of syscall where the
31 // syscalls only read state from the kernel. However, since Go's
32 // runtime freely migrates code execution between threads, support of
33 // this type is required for any successful attempt to fully drop or
34 // modify the privilege of a running Go program under Linux.
35 //
36 // More info on how Linux privilege works and examples of using this
37 // package can be found on the [Fully Capable site].
38 //
39 // WARNING: For older go toolchains (prior to go1.16), the code should
40 // mostly work as far back as go1.11. However, like support for
41 // C.setuid(), this support is fragile and may hang. See the above bug
42 // for details.
43 //
44 // Copyright (c) 2019,20,24 Andrew G. Morgan <[email protected]>
45 //
46 // The psx package is licensed with a (you choose) BSD 3-clause or
47 // GPL2. See LICENSE file for details.
48 //
49 // [Bug 219478]: https://bugzilla.kernel.org/show_bug.cgi?id=219478
50 // [Fully Capable site]: https://sites.google.com/site/fullycapable
51 package psx // import "kernel.org/pub/linux/libs/security/libcap/psx"