Provided by: manpages-dev_3.35-0.1ubuntu1_all bug

NAME

       prctl - operations on a process

SYNOPSIS

       #include <sys/prctl.h>

       int prctl(int option, unsigned long arg2, unsigned long arg3,
                 unsigned long arg4, unsigned long arg5);

DESCRIPTION

       prctl()  is  called  with  a  first argument describing what to do (with values defined in
       <linux/prctl.h>), and further arguments with a significance depending on  the  first  one.
       The first argument can be:

       PR_CAPBSET_READ (since Linux 2.6.25)
              Return  (as  the  function  result) 1 if the capability specified in arg2 is in the
              calling thread's capability bounding set, or 0  if  it  is  not.   (The  capability
              constants  are  defined  in  <linux/capability.h>.)   The  capability  bounding set
              dictates whether the process can receive the capability through a file's  permitted
              capability set on a subsequent call to execve(2).

              If  the  capability  specified  in  arg2 is not valid, then the call fails with the
              error EINVAL.

       PR_CAPBSET_DROP (since Linux 2.6.25)
              If the calling thread has the CAP_SETPCAP  capability,  then  drop  the  capability
              specified  by arg2 from the calling thread's capability bounding set.  Any children
              of the calling thread will inherit the newly reduced bounding set.

              The call fails with the error: EPERM if  the  calling  thread  does  not  have  the
              CAP_SETPCAP;  EINVAL  if  arg2  does not represent a valid capability; or EINVAL if
              file capabilities are not enabled in the kernel, in which case  bounding  sets  are
              not supported.

       PR_SET_DUMPABLE (since Linux 2.3.20)
              Set  the  state  of  the  flag determining whether core dumps are produced for this
              process upon delivery of a signal whose default behavior is to produce a core dump.
              (Normally  this flag is set for a process by default, but it is cleared when a set-
              user-ID or set-group-ID program is executed and also by various system  calls  that
              manipulate  process  UIDs  and  GIDs).  In kernels up to and including 2.6.12, arg2
              must be either 0 (process is not dumpable) or 1  (process  is  dumpable).   Between
              kernels  2.6.13 and 2.6.17, the value 2 was also permitted, which caused any binary
              which normally would not be dumped to be dumped readable by root only; for security
              reasons,   this   feature   has   been  removed.   (See  also  the  description  of
              /proc/sys/fs/suid_dumpable in proc(5).)  Processes that are not dumpable can not be
              attached via ptrace(2) PTRACE_ATTACH.

       PR_GET_DUMPABLE (since Linux 2.3.20)
              Return (as the function result) the current state of the calling process's dumpable
              flag.

       PR_SET_ENDIAN (since Linux 2.6.18, PowerPC only)
              Set the endian-ness of the calling process to the value given in arg2, which should
              be  one  of the following: PR_ENDIAN_BIG, PR_ENDIAN_LITTLE, or PR_ENDIAN_PPC_LITTLE
              (PowerPC pseudo little endian).

       PR_GET_ENDIAN (since Linux 2.6.18, PowerPC only)
              Return the endian-ness of the calling  process,  in  the  location  pointed  to  by
              (int *) arg2.

       PR_SET_FPEMU (since Linux 2.4.18, 2.5.9, only on ia64)
              Set  floating-point  emulation  control  bits  to  arg2.   Pass PR_FPEMU_NOPRINT to
              silently emulate fp operations accesses,  or  PR_FPEMU_SIGFPE  to  not  emulate  fp
              operations and send SIGFPE instead.

       PR_GET_FPEMU (since Linux 2.4.18, 2.5.9, only on ia64)
              Return floating-point emulation control bits, in the location pointed to by (int *)
              arg2.

       PR_SET_FPEXC (since Linux 2.4.21, 2.5.32, only on PowerPC)
              Set floating-point exception mode to arg2.  Pass PR_FP_EXC_SW_ENABLE to  use  FPEXC
              for  FP  exception  enables,  PR_FP_EXC_DIV  for  floating-point  divide  by  zero,
              PR_FP_EXC_OVF  for  floating-point  overflow,  PR_FP_EXC_UND   for   floating-point
              underflow,  PR_FP_EXC_RES  for  floating-point  inexact  result,  PR_FP_EXC_INV for
              floating-point invalid operation, PR_FP_EXC_DISABLED for  FP  exceptions  disabled,
              PR_FP_EXC_NONRECOV  for  async  nonrecoverable  exception mode, PR_FP_EXC_ASYNC for
              async recoverable exception mode, PR_FP_EXC_PRECISE for precise exception mode.

       PR_GET_FPEXC (since Linux 2.4.21, 2.5.32, only on PowerPC)
              Return floating-point exception mode, in the location pointed to by (int *) arg2.

       PR_SET_KEEPCAPS (since Linux 2.2.18)
              Set the state of the thread's "keep capabilities" flag,  which  determines  whether
              the  threads's  permitted  capability  set  is cleared when a change is made to the
              threads's user IDs such that the threads's real UID, effective UID, and saved  set-
              user-ID  all  become  nonzero when at least one of them previously had the value 0.
              By default, the permitted capability set is cleared when such  a  change  is  made;
              setting  the "keep capabilities" flag prevents it from being cleared.  arg2 must be
              either 0 (permitted capabilities are cleared)  or  1  (permitted  capabilities  are
              kept).   (A  thread's  effective  capability  set  is  always  cleared  when such a
              credential change is made, regardless of the setting  of  the  "keep  capabilities"
              flag.)   The  "keep  capabilities"  value will be reset to 0 on subsequent calls to
              execve(2).

       PR_GET_KEEPCAPS (since Linux 2.2.18)
              Return (as the function result) the current state of the  calling  threads's  "keep
              capabilities" flag.

       PR_SET_NAME (since Linux 2.6.9)
              Set  the  process  name  for  the  calling process, using the value in the location
              pointed to by (char *) arg2.  The name can be up to 16 bytes long,  and  should  be
              null-terminated if it contains fewer bytes.

       PR_GET_NAME (since Linux 2.6.11)
              Return  the  process  name  for  the  calling  process, in the buffer pointed to by
              (char *) arg2.  The buffer should allow space for up  to  16  bytes;  the  returned
              string will be null-terminated if it is shorter than that.

       PR_SET_PDEATHSIG (since Linux 2.1.57)
              Set the parent process death signal of the calling process to arg2 (either a signal
              value in the range 1..maxsig, or 0 to clear).  This is the signal that the  calling
              process  will  get  when its parent dies.  This value is cleared for the child of a
              fork(2).

       PR_GET_PDEATHSIG (since Linux 2.3.15)
              Return the current value of the  parent  process  death  signal,  in  the  location
              pointed to by (int *) arg2.

       PR_SET_PTRACER (since Ubuntu 10.10)
              Sets  the  top  of  the  process  tree that is allowed to use PTRACE on the calling
              process, assuming other requirements are met (matching uid,  wasn't  setuid,  etc).
              The  allowed process id is specified in arg2 (or 0 to clear). For more details, see
              /etc/sysctl.d/10-ptrace.conf.

       PR_SET_SECCOMP (since Linux 2.6.23)
              Set  the  secure  computing  mode  for  the  calling  thread.    In   the   current
              implementation, arg2 must be 1.  After the secure computing mode has been set to 1,
              the only system calls that the thread is permitted to make are  read(2),  write(2),
              _exit(2), and sigreturn(2).  Other system calls result in the delivery of a SIGKILL
              signal.  Secure computing mode is useful for number-crunching applications that may
              need  to  execute  untrusted  byte code, perhaps obtained by reading from a pipe or
              socket.  This operation  is  only  available  if  the  kernel  is  configured  with
              CONFIG_SECCOMP enabled.

       PR_GET_SECCOMP (since Linux 2.6.23)
              Return  the  secure  computing mode of the calling thread.  Not very useful for the
              current implementation (mode equals 1), but may be useful for other possible future
              modes:  if the caller is not in secure computing mode, this operation returns 0; if
              the caller is in secure computing mode, then the prctl() call will cause a  SIGKILL
              signal  to  be sent to the process.  This operation is only available if the kernel
              is configured with CONFIG_SECCOMP enabled.

       PR_SET_SECUREBITS (since Linux 2.6.26)
              Set the "securebits" flags of the calling thread to the  value  supplied  in  arg2.
              See capabilities(7).

       PR_GET_SECUREBITS (since Linux 2.6.26)
              Return  (as the function result) the "securebits" flags of the calling thread.  See
              capabilities(7).

       PR_SET_TIMING (since Linux 2.6.0-test4)
              Set whether to use (normal, traditional) statistical  process  timing  or  accurate
              timestamp-based    process    timing,    by    passing   PR_TIMING_STATISTICAL   or
              PR_TIMING_TIMESTAMP to arg2.   PR_TIMING_TIMESTAMP  is  not  currently  implemented
              (attempting to set this mode will yield the error EINVAL).

       PR_GET_TIMING (since Linux 2.6.0-test4)
              Return (as the function result) which process timing method is currently in use.

       PR_SET_TSC (since Linux 2.6.26, x86 only)
              Set  the state of the flag determining whether the timestamp counter can be read by
              the process.  Pass PR_TSC_ENABLE to arg2 to allow it to be read, or  PR_TSC_SIGSEGV
              to generate a SIGSEGV when the process tries to read the timestamp counter.

       PR_GET_TSC (since Linux 2.6.26, x86 only)
              Return the state of the flag determining whether the timestamp counter can be read,
              in the location pointed to by (int *) arg2.

       PR_SET_UNALIGN
              (Only on: ia64, since Linux 2.3.48; parisc,  since  Linux  2.6.15;  PowerPC,  since
              Linux 2.6.18; Alpha, since Linux 2.6.22) Set unaligned access control bits to arg2.
              Pass  PR_UNALIGN_NOPRINT  to  silently  fix  up   unaligned   user   accesses,   or
              PR_UNALIGN_SIGBUS to generate SIGBUS on unaligned user access.

       PR_GET_UNALIGN
              (see PR_SET_UNALIGN for information on versions and architectures) Return unaligned
              access control bits, in the location pointed to by (int *) arg2.

       PR_MCE_KILL (since Linux 2.6.32)
              Set the machine check memory corruption kill policy for  the  current  thread.   If
              arg2  is  PR_MCE_KILL_CLEAR, clear the thread memory corruption kill policy and use
              the   system-wide   default.    (The   system-wide   default    is    defined    by
              /proc/sys/vm/memory_failure_early_kill;  see proc(5).)  If arg2 is PR_MCE_KILL_SET,
              use a thread-specific memory corruption kill policy.  In this  case,  arg3  defines
              whether the policy is early kill (PR_MCE_KILL_EARLY), late kill (PR_MCE_KILL_LATE),
              or the system-wide default (PR_MCE_KILL_DEFAULT).  Early kill means that the thread
              receives  a  SIGBUS signal as soon as hardware memory corruption is detected inside
              its address space.  In late kill mode, the process is only killed when it  accesses
              a corrupted page.  See sigaction(2) for more information on the SIGBUS signal.  The
              policy is inherited by children.  The remaining unused prctl()  arguments  must  be
              zero for future compatibility.

       PR_MCE_KILL_GET (since Linux 2.6.32)
              Return  the  current  per-process  machine  check  kill policy.  All unused prctl()
              arguments must be zero.

RETURN VALUE

       On   success,   PR_GET_DUMPABLE,    PR_GET_KEEPCAPS,    PR_CAPBSET_READ,    PR_GET_TIMING,
       PR_GET_SECUREBITS,   PR_MCE_KILL_GET,  and  (if  it  returns)  PR_GET_SECCOMP  return  the
       nonnegative values described above.  All other option values  return  0  on  success.   On
       error, -1 is returned, and errno is set appropriately.

ERRORS

       EFAULT arg2 is an invalid address.

       EINVAL The value of option is not recognized.

       EINVAL option  is  PR_MCE_KILL  or  PR_MCE_KILL_GET, and unused prctl() arguments were not
              specified as zero.

       EINVAL arg2 is not valid value for this option.

       EINVAL option is PR_SET_SECCOMP or PR_SET_SECCOMP, and the kernel was not configured  with
              CONFIG_SECCOMP.

       EPERM  option  is  PR_SET_SECUREBITS,  and  the  caller  does  not  have  the  CAP_SETPCAP
              capability, or tried to unset a "locked"  flag,  or  tried  to  set  a  flag  whose
              corresponding locked flag was set (see capabilities(7)).

       EPERM  option  is  PR_SET_KEEPCAPS,  and the callers's SECURE_KEEP_CAPS_LOCKED flag is set
              (see capabilities(7)).

       EPERM  option is PR_CAPBSET_DROP, and the caller does not have the CAP_SETPCAP capability.

VERSIONS

       The prctl() system call was introduced in Linux 2.1.57.

CONFORMING TO

       This call is Linux-specific.  IRIX has a prctl() system call  (also  introduced  in  Linux
       2.1.44 as irix_prctl on the MIPS architecture), with prototype

       ptrdiff_t prctl(int option, int arg2, int arg3);

       and  options  to  get  the maximum number of processes per user, get the maximum number of
       processors the calling process can use, find out whether a specified process is  currently
       blocked, get or set the maximum stack size, etc.

SEE ALSO

       signal(2), core(5)

COLOPHON

       This  page  is  part of release 3.35 of the Linux man-pages project.  A description of the
       project, and information about reporting bugs, can be found at  http://man7.org/linux/man-
       pages/.