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/.