1// Package psx provides support for system calls that are run 2// simultanously on all threads under Linux. 3// 4// This property can be used to work around a historical lack of 5// native Go support for such a feature. Something that is the subject 6// of: 7// 8// https://github.com/golang/go/issues/1435 9// 10// The package works differently depending on whether or not 11// CGO_ENABLED is 0 or 1. 12// 13// In the former case, psx is a low overhead wrapper for the two 14// native go calls: syscall.AllThreadsSyscall() and 15// syscall.AllThreadsSyscall6() [expected to be] introduced in 16// go1.16. We provide this wrapping to minimize client source code 17// changes when compiling with or without CGo enabled. 18// 19// In the latter case, and toolchains prior to go1.16, it works via 20// CGo wrappers for system call functions that call the C [lib]psx 21// functions of these names. This ensures that the system calls 22// execute simultaneously on all the pthreads of the Go (and CGo) 23// combined runtime. 24// 25// With CGo, the psx support works in the following way: the pthread 26// that is first asked to execute the syscall does so, and determines 27// if it succeeds or fails. If it fails, it returns immediately 28// without attempting the syscall on other pthreads. If the initial 29// attempt succeeds, however, then the runtime is stopped in order for 30// the same system call to be performed on all the remaining pthreads 31// of the runtime. Once all pthreads have completed the syscall, the 32// return codes are those obtained by the first pthread's invocation 33// of the syscall. 34// 35// Note, there is no need to use this variant of syscall where the 36// syscalls only read state from the kernel. However, since Go's 37// runtime freely migrates code execution between pthreads, support of 38// this type is required for any successful attempt to fully drop or 39// modify the privilege of a running Go program under Linux. 40// 41// More info on how Linux privilege works and examples of using this 42// package can be found here: 43// 44// https://sites.google.com/site/fullycapable 45// 46// WARNING: For older go toolchains (prior to go1.15), correct 47// compilation of this package may require an extra workaround step: 48// 49// The workaround is to build with the following CGO_LDFLAGS_ALLOW in 50// effect (here the syntax is that of bash for defining an environment 51// variable): 52// 53// export CGO_LDFLAGS_ALLOW="-Wl,-?-wrap[=,][^-.@][^,]*" 54// 55// 56// Copyright (c) 2019,20 Andrew G. Morgan <morgan@kernel.org> 57// 58// The psx package is licensed with a (you choose) BSD 3-clause or 59// GPL2. See LICENSE file for details. 60package psx // import "kernel.org/pub/linux/libs/security/libcap/psx" 61