focal (3) libpsx.3.gz

NAME

       psx_syscall3, psx_syscall6 - POSIX semantics for system calls

SYNOPSIS

       #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);

       Link with one of these:

       ld ... -lpsx -lpthread --wrap=pthread_create

       gcc ... -lpsx -lpthread -Wl,-wrap,pthread_create

DESCRIPTION

       The  libpsx  library  attempts  to  fill  a  gap  left  by the pthreads(7) implementation on Linux. To be
       compliant POSIX threads, via the  nptl(7)  setxid  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,
       libpsx(3)  provides  a  more  generic  pair  of  wrapping  system  call  functions:  psx_syscall3(3)  and
       psx_syscall6(3).  Like the setxid mechanism, the coordination of thread state is arranged by  a  realtime
       signal SIGRTMAX which is usurped for this process.

       A  linker  trick of wrapping the pthread_create() call with a psx thread registration function is used to
       allow libpsx to keep track of all pthreads. If that trick is not usable by  your  application,  then  the
       much  more cumbersome and fragile psx_register(pthread_t thread) function is provided to register threads
       manually with the library. To successfully use this approach an explanation of how  to  code  for  it  is
       provided at the top of the <sys/psx_syscall.h> header file.

       An  inefficient  macrology trick supports the 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 psx_syscall3(3)  or
       psx_syscall6(3)  with  zeros  filling the missing arguments. While using this in source code will make it
       appear clean, the actual code  footprint  is  larger.  You  are  encouraged  to  use  the  more  explicit
       psx_syscall3(3) and psx_syscall6(3) functions.

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 errno(3) is set  to  the  detailed  error  value.  The  psx_syscall3  and
       psx_syscall6  functions  attempt  a  single threaded system call and return immediately in the case of an
       error. Should this call succeed, then the same system calls are executed from a signal handler on each of
       the other threads of the process.

CONFORMING TO

       The needs of libcap(3) for POSIX semantics of capability manipulation.

REPORTING BUGS

       Please report bugs via:

       https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1047723&product=Tools&resolution=---

SEE ALSO

       libcap(3), pthreads(7) and nptl(7).

                                                   2020-01-07                                          LIBPSX(3)