original/man2/prctl.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl)
   4 .\" and Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\" and Copyright Guillem Jover <guillem@hadrons.org>
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\"
  27 .\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG
  28 .\" Modified 27 Jun 02, Michael Kerrisk
  29 .\"     Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
  30 .\"     PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
  31 .\" Modified 2006-08-30 Guillem Jover <guillem@hadrons.org>
  32 .\"     Updated Linux versions where the options where introduced.
  33 .\"     Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
  34 .\"     PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
  35 .\"     PR_SET_FPEXC, PR_GET_FPEXC
  36 .\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP
  37 .\" 2008-06-13 Erik Bosman, <ejbosman@cs.vu.nl>
  38 .\"     Document PR_GET_TSC and PR_SET_TSC.
  39 .\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
  40 .\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
  41 .\"
  42 .\" FIXME: Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK (new in 2.6.28)
  43 .\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
  44 .\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
  45 .\"
  46 .TH PRCTL 2 2010-05-13 "Linux" "Linux Programmer's Manual"
  47 .SH NAME
  48 prctl \- operations on a process
  49 .SH SYNOPSIS
  50 .nf
  51 .B #include <sys/prctl.h>
  52 .sp
  53 .BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
  54 .BI "          unsigned long " arg4 ", unsigned long " arg5 );
  55 .fi
  56 .SH DESCRIPTION
  57 .BR prctl ()
  58 is called with a first argument describing what to do
  59 (with values defined in \fI<linux/prctl.h>\fP), and further
  60 arguments with a significance depending on the first one.
  61 The first argument can be:
  62 .TP
  63 .BR PR_CAPBSET_READ " (since Linux 2.6.25)
  64 Return (as the function result) 1 if the capability specified in
  65 .I arg2
  66 is in the calling thread's capability bounding set,
  67 or 0 if it is not.
  68 (The capability constants are defined in
  69 .IR <linux/capability.h> .)
  70 The capability bounding set dictates
  71 whether the process can receive the capability through a
  72 file's permitted capability set on a subsequent call to
  73 .BR execve (2).
  74
  75 If the capability specified in
  76 .I arg2
  77 is not valid, then the call fails with the error
  78 .BR EINVAL .
  79 .TP
  80 .BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
  81 If the calling thread has the
  82 .B CAP_SETPCAP
  83 capability, then drop the capability specified by
  84 .I arg2
  85 from the calling thread's capability bounding set.
  86 Any children of the calling thread will inherit the newly
  87 reduced bounding set.
  88
  89 The call fails with the error:
  90 .B EPERM
  91 if the calling thread does not have the
  92 .BR CAP_SETPCAP ;
  93 .BR EINVAL
  94 if
  95 .I arg2
  96 does not represent a valid capability; or
  97 .BR EINVAL
  98 if file capabilities are not enabled in the kernel,
  99 in which case bounding sets are not supported.
 100 .TP
 101 .BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
 102 Set the state of the flag determining whether core dumps are produced
 103 for this process upon delivery of a signal whose default behavior is
 104 to produce a core dump.
 105 (Normally this flag is set for a process by default, but it is cleared
 106 when a set-user-ID or set-group-ID program is executed and also by
 107 various system calls that manipulate process UIDs and GIDs).
 108 In kernels up to and including 2.6.12,
 109 .I arg2
 110 must be either 0 (process is not dumpable) or 1 (process is dumpable).
 111 Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
 112 which caused any binary which normally would not be dumped
 113 to be dumped readable by root only;
 114 for security reasons, this feature has been removed.
 115 .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
 116 .\" Subject:    Fix prctl privilege escalation (CVE-2006-2451)
 117 .\" From:       Marcel Holtmann <marcel () holtmann ! org>
 118 .\" Date:       2006-07-12 11:12:00
 119 (See also the description of
 120 .I /proc/sys/fs/suid_dumpable
 121 in
 122 .BR proc (5).)
 123 .TP
 124 .BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
 125 Return (as the function result) the current state of the calling
 126 process's dumpable flag.
 127 .\" Since Linux 2.6.13, the dumpable flag can have the value 2,
 128 .\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
 129 .\" flags has a nonzero value.  This was fixed in 2.6.14.
 130 .TP
 131 .BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
 132 Set the endian-ness of the calling process to the value given
 133 in \fIarg2\fP, which should be one of the following:
 134 .\" Respectively 0, 1, 2
 135 .BR PR_ENDIAN_BIG ,
 136 .BR PR_ENDIAN_LITTLE ,
 137 or
 138 .B PR_ENDIAN_PPC_LITTLE
 139 (PowerPC pseudo little endian).
 140 .TP
 141 .BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
 142 Return the endian-ness of the calling process,
 143 in the location pointed to by
 144 .IR "(int\ *) arg2" .
 145 .TP
 146 .BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
 147 Set floating-point emulation control bits to \fIarg2\fP.
 148 Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
 149 \fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
 150 .B SIGFPE
 151 instead.
 152 .TP
 153 .BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
 154 Return floating-point emulation control bits,
 155 in the location pointed to by
 156 .IR "(int\ *) arg2" .
 157 .TP
 158 .BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
 159 Set floating-point exception mode to \fIarg2\fP.
 160 Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
 161 \fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
 162 \fBPR_FP_EXC_OVF\fP for floating-point overflow,
 163 \fBPR_FP_EXC_UND\fP for floating-point underflow,
 164 \fBPR_FP_EXC_RES\fP for floating-point inexact result,
 165 \fBPR_FP_EXC_INV\fP for floating-point invalid operation,
 166 \fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
 167 \fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
 168 \fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
 169 \fBPR_FP_EXC_PRECISE\fP for precise exception mode.
 170 .TP
 171 .BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
 172 Return floating-point exception mode,
 173 in the location pointed to by
 174 .IR "(int\ *) arg2" .
 175 .TP
 176 .BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
 177 Set the state of the thread's "keep capabilities" flag,
 178 which determines whether the threads's permitted
 179 capability set is cleared when a change is made to the threads's user IDs
 180 such that the threads's real UID, effective UID, and saved set-user-ID
 181 all become nonzero when at least one of them previously had the value 0.
 182 By default, the permitted capability set is cleared when such a change is made;
 183 setting the "keep capabilities" flag prevents it from being cleared.
 184 .I arg2
 185 must be either 0 (permitted capabilities are cleared)
 186 or 1 (permitted capabilities are kept).
 187 (A thread's
 188 .I effective
 189 capability set is always cleared when such a credential change is made,
 190 regardless of the setting of the "keep capabilities" flag.)
 191 The "keep capabilities" value will be reset to 0 on subsequent calls to
 192 .BR execve (2).
 193 .TP
 194 .BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
 195 Return (as the function result) the current state of the calling threads's
 196 "keep capabilities" flag.
 197 .TP
 198 .BR PR_SET_NAME " (since Linux 2.6.9)"
 199 Set the process name for the calling process,
 200 using the value in the location pointed to by
 201 .IR "(char\ *) arg2" .
 202 The name can be up to 16 bytes long,
 203 .\" TASK_COMM_LEN in include/linux/sched.h
 204 and should be null-terminated if it contains fewer bytes.
 205 .TP
 206 .BR PR_GET_NAME " (since Linux 2.6.11)"
 207 Return the process name for the calling process,
 208 in the buffer pointed to by
 209 .IR "(char\ *) arg2" .
 210 The buffer should allow space for up to 16 bytes;
 211 the returned string will be null-terminated if it is shorter than that.
 212 .TP
 213 .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
 214 Set the parent process death signal
 215 of the calling process to \fIarg2\fP (either a signal value
 216 in the range 1..maxsig, or 0 to clear).
 217 This is the signal that the calling process will get when its
 218 parent dies.
 219 This value is cleared for the child of a
 220 .BR fork (2).
 221 .TP
 222 .BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
 223 Return the current value of the parent process death signal,
 224 in the location pointed to by
 225 .IR "(int\ *) arg2" .
 226 .TP
 227 .BR PR_SET_SECCOMP " (since Linux 2.6.23)"
 228 .\" See http://thread.gmane.org/gmane.linux.kernel/542632
 229 .\" [PATCH 0 of 2] seccomp updates
 230 .\" andrea@cpushare.com
 231 Set the secure computing mode for the calling thread.
 232 In the current implementation,
 233 .IR arg2
 234 must be 1.
 235 After the secure computing mode has been set to 1,
 236 the only system calls that the thread is permitted to make are
 237 .BR read (2),
 238 .BR write (2),
 239 .BR _exit (2),
 240 and
 241 .BR sigreturn (2).
 242 Other system calls result in the delivery of a
 243 .BR SIGKILL
 244 signal.
 245 Secure computing mode is useful for number-crunching applications
 246 that may need to execute untrusted byte code,
 247 perhaps obtained by reading from a pipe or socket.
 248 This operation is only available
 249 if the kernel is configured with CONFIG_SECCOMP enabled.
 250 .TP
 251 .BR PR_GET_SECCOMP " (since Linux 2.6.23)"
 252 Return the secure computing mode of the calling thread.
 253 Not very useful for the current implementation (mode equals 1),
 254 but may be useful for other possible future modes:
 255 if the caller is not in secure computing mode, this operation returns 0;
 256 if the caller is in secure computing mode, then the
 257 .BR prctl ()
 258 call will cause a
 259 .B SIGKILL
 260 signal to be sent to the process.
 261 This operation is only available
 262 if the kernel is configured with CONFIG_SECCOMP enabled.
 263 .TP
 264 .BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
 265 Set the "securebits" flags of the calling thread to the value supplied in
 266 .IR arg2 .
 267 See
 268 .BR capabilities (7).
 269 .TP
 270 .BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
 271 Return (as the function result)
 272 the "securebits" flags of the calling thread.
 273 See
 274 .BR capabilities (7).
 275 .TP
 276 .BR PR_SET_TIMING " (since Linux 2.6.0-test4)"
 277 Set whether to use (normal, traditional) statistical process timing or
 278 accurate timestamp-based process timing, by passing
 279 .B PR_TIMING_STATISTICAL
 280 .\" 0
 281 or
 282 .B PR_TIMING_TIMESTAMP
 283 .\" 1
 284 to \fIarg2\fP.
 285 .B PR_TIMING_TIMESTAMP
 286 is not currently implemented
 287 (attempting to set this mode will yield the error
 288 .BR EINVAL ).
 289 .\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
 290 .\" and looking at the patch history, it appears
 291 .\" that it never did anything.
 292 .TP
 293 .BR PR_GET_TIMING " (since Linux 2.6.0-test4)"
 294 Return (as the function result) which process timing method is currently
 295 in use.
 296 .TP
 297 .BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
 298 Set the state of the flag determining whether the timestamp counter
 299 can be read by the process.
 300 Pass
 301 .B PR_TSC_ENABLE
 302 to
 303 .I arg2
 304 to allow it to be read, or
 305 .B PR_TSC_SIGSEGV
 306 to generate a
 307 .B SIGSEGV
 308 when the process tries to read the timestamp counter.
 309 .TP
 310 .BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
 311 Return the state of the flag determining whether the timestamp counter
 312 can be read,
 313 in the location pointed to by
 314 .IR "(int\ *) arg2" .
 315 .TP
 316 .B PR_SET_UNALIGN
 317 (Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
 318 PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22)
 319 Set unaligned access control bits to \fIarg2\fP.
 320 Pass
 321 \fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses,
 322 or \fBPR_UNALIGN_SIGBUS\fP to generate
 323 .B SIGBUS
 324 on unaligned user access.
 325 .TP
 326 .B PR_GET_UNALIGN
 327 (see
 328 .B PR_SET_UNALIGN
 329 for information on versions and architectures)
 330 Return unaligned access control bits, in the location pointed to by
 331 .IR "(int\ *) arg2" .
 332 .TP
 333 .BR PR_MCE_KILL " (since Linux 2.6.32)"
 334 Set the machine check memory corruption kill policy for the current thread.
 335 If
 336 .I arg2
 337 is
 338 .BR PR_MCE_KILL_CLEAR ,
 339 clear the thread memory corruption kill policy and use the system-wide default.
 340 (The system-wide default is defined by
 341 .IR /proc/sys/vm/memory_failure_early_kill ;
 342 see
 343 .BR proc (5).)
 344 If
 345 .I arg2
 346 is
 347 .BR PR_MCE_KILL_SET ,
 348 use a thread-specific memory corruption kill policy.
 349 In this case,
 350 .I arg3
 351 defines whether the policy is
 352 .I early kill
 353 .RB ( PR_MCE_KILL_EARLY ),
 354 .I late kill
 355 .RB ( PR_MCE_KILL_LATE ),
 356 or the system-wide default
 357 .RB ( PR_MCE_KILL_DEFAULT ).
 358 Early kill means that the task receives a
 359 .B SIGBUS
 360 signal as soon as hardware memory corruption is detected inside
 361 its address space.
 362 In late kill mode, the process is only killed when it accesses a corrupted page.
 363 See
 364 .I sigaction(2)
 365 for more information on the
 366 .BR SIGBUS
 367 signal.
 368 The policy is inherited by children.
 369 The remaining unused
 370 .BR prctl ()
 371 arguments must be zero for future compatibility.
 372 .TP
 373 .BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
 374 Return the current per-process machine check kill policy.
 375 All unused
 376 .BR prctl ()
 377 arguments must be zero.
 378 .SH "RETURN VALUE"
 379 On success,
 380 .BR PR_GET_DUMPABLE ,
 381 .BR PR_GET_KEEPCAPS ,
 382 .BR PR_CAPBSET_READ ,
 383 .BR PR_GET_TIMING ,
 384 .BR PR_GET_SECUREBITS ,
 385 .BR PR_MCE_KILL_GET ,
 386 and (if it returns)
 387 .BR PR_GET_SECCOMP
 388 return the nonnegative values described above.
 389 All other
 390 .I option
 391 values return 0 on success.
 392 On error, \-1 is returned, and
 393 .I errno
 394 is set appropriately.
 395 .SH ERRORS
 396 .TP
 397 .B EFAULT
 398 .I arg2
 399 is an invalid address.
 400 .TP
 401 .B EINVAL
 402 The value of
 403 .I option
 404 is not recognized.
 405 .TP
 406 .B EINVAL
 407 .I option
 408 is
 409 .BR PR_MCE_KILL
 410 or
 411 .BR PR_MCE_KILL_GET ,
 412 and unused
 413 .BR prctl ()
 414 arguments were not specified as zero.
 415 .TP
 416 .B EINVAL
 417 .I arg2
 418 is not valid value for this
 419 .IR option .
 420 .TP
 421 .B EINVAL
 422 .I option
 423 is
 424 .BR PR_SET_SECCOMP
 425 or
 426 .BR PR_SET_SECCOMP ,
 427 and the kernel was not configured with
 428 .BR CONFIG_SECCOMP .
 429 .TP
 430 .B EPERM
 431 .I option
 432 is
 433 .BR PR_SET_SECUREBITS ,
 434 and the caller does not have the
 435 .B CAP_SETPCAP
 436 capability,
 437 or tried to unset a "locked" flag,
 438 or tried to set a flag whose corresponding locked flag was set
 439 (see
 440 .BR capabilities (7)).
 441 .TP
 442 .B EPERM
 443 .I option
 444 is
 445 .BR PR_SET_KEEPCAPS ,
 446 and the callers's
 447 .B SECURE_KEEP_CAPS_LOCKED
 448 flag is set
 449 (see
 450 .BR capabilities (7)).
 451 .TP
 452 .B EPERM
 453 .I option
 454 is
 455 .BR PR_CAPBSET_DROP ,
 456 and the caller does not have the
 457 .B CAP_SETPCAP
 458 capability.
 459 .\" The following can't actually happen, because prctl() in
 460 .\" seccomp mode will cause SIGKILL.
 461 .\" .TP
 462 .\" .B EPERM
 463 .\" .I option
 464 .\" is
 465 .\" .BR PR_SET_SECCOMP ,
 466 .\" and secure computing mode is already 1.
 467 .SH VERSIONS
 468 The
 469 .BR prctl ()
 470 system call was introduced in Linux 2.1.57.
 471 .\" The library interface was added in glibc 2.0.6
 472 .SH "CONFORMING TO"
 473 This call is Linux-specific.
 474 IRIX has a
 475 .BR prctl ()
 476 system call (also introduced in Linux 2.1.44
 477 as irix_prctl on the MIPS architecture),
 478 with prototype
 479 .sp
 480 .BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
 481 .sp
 482 and options to get the maximum number of processes per user,
 483 get the maximum number of processors the calling process can use,
 484 find out whether a specified process is currently blocked,
 485 get or set the maximum stack size, etc.
 486 .SH "SEE ALSO"
 487 .BR signal (2),
 488 .BR core (5)