1PRCTL(2) Linux Programmer's Manual PRCTL(2)
2
6 prctl - operations on a process
7
9 #include <sys/prctl.h>
10 int prctl(int option, unsigned long arg2, unsigned long arg3,
12 unsigned long arg4, unsigned long arg5);
13
15 prctl() is called with a first argument describing what to do (with
16 values defined in <linux/prctl.h>), and further arguments with a sig‐
17 nificance depending on the first one. The first argument can be:
18 PR_CAPBSET_READ (since Linux 2.6.25)
20 Return (as the function result) 1 if the capability specified in
21 arg2 is in the calling thread's capability bounding set, or 0 if
22 it is not. (The capability constants are defined in
23 <linux/capability.h>.) The capability bounding set dictates
24 whether the process can receive the capability through a file's
25 permitted capability set on a subsequent call to execve(2).
26 If the capability specified in arg2 is not valid, then the call
28 fails with the error EINVAL.
29 PR_CAPBSET_DROP (since Linux 2.6.25)
31 If the calling thread has the CAP_SETPCAP capability, then drop
32 the capability specified by arg2 from the calling thread's capa‐
33 bility bounding set. Any children of the calling thread will
34 inherit the newly reduced bounding set.
35 The call fails with the error: EPERM if the calling thread does
37 not have the CAP_SETPCAP; EINVAL if arg2 does not represent a
38 valid capability; or EINVAL if file capabilities are not enabled
39 in the kernel, in which case bounding sets are not supported.
40 PR_SET_CHILD_SUBREAPER (since Linux 3.4)
42 If arg2 is nonzero, set the "child subreaper" attribute of the
43 calling process; if arg2 is zero, unset the attribute. When a
44 process is marked as a child subreaper, all of the children that
45 it creates, and their descendants, will be marked as having a
46 subreaper. In effect, a subreaper fulfills the role of init(1)
47 for its descendant processes. Upon termination of a process
48 that is orphaned (i.e., its immediate parent has already termi‐
49 nated) and marked as having a subreaper, the nearest still liv‐
50 ing ancestor subreaper will receive a SIGCHLD signal and be able
51 to wait(2) on the process to discover its termination status.
52 PR_GET_CHILD_SUBREAPER (since Linux 3.4)
54 Return the "child subreaper" setting of the caller, in the loca‐
55 tion pointed to by (int *) arg2.
56 PR_SET_DUMPABLE (since Linux 2.3.20)
58 Set the state of the flag determining whether core dumps are
59 produced for the calling process upon delivery of a signal whose
60 default behavior is to produce a core dump. (Normally, this
61 flag is set for a process by default, but it is cleared when a
62 set-user-ID or set-group-ID program is executed and also by var‐
63 ious system calls that manipulate process UIDs and GIDs). In
64 kernels up to and including 2.6.12, arg2 must be either 0
65 (process is not dumpable) or 1 (process is dumpable). Between
66 kernels 2.6.13 and 2.6.17, the value 2 was also permitted, which
67 caused any binary which normally would not be dumped to be
68 dumped readable by root only; for security reasons, this feature
69 has been removed. (See also the description of
70 /proc/sys/fs/suid_dumpable in proc(5).) Processes that are not
71 dumpable can not be attached via ptrace(2) PTRACE_ATTACH.
72 PR_GET_DUMPABLE (since Linux 2.3.20)
74 Return (as the function result) the current state of the calling
75 process's dumpable flag.
76 PR_SET_ENDIAN (since Linux 2.6.18, PowerPC only)
78 Set the endian-ness of the calling process to the value given in
79 arg2, which should be one of the following: PR_ENDIAN_BIG,
80 PR_ENDIAN_LITTLE, or PR_ENDIAN_PPC_LITTLE (PowerPC pseudo little
81 endian).
82 PR_GET_ENDIAN (since Linux 2.6.18, PowerPC only)
84 Return the endian-ness of the calling process, in the location
85 pointed to by (int *) arg2.
86 PR_SET_FPEMU (since Linux 2.4.18, 2.5.9, only on ia64)
88 Set floating-point emulation control bits to arg2. Pass
89 PR_FPEMU_NOPRINT to silently emulate fp operations accesses, or
90 PR_FPEMU_SIGFPE to not emulate fp operations and send SIGFPE
91 instead.
92 PR_GET_FPEMU (since Linux 2.4.18, 2.5.9, only on ia64)
94 Return floating-point emulation control bits, in the location
95 pointed to by (int *) arg2.
96 PR_SET_FPEXC (since Linux 2.4.21, 2.5.32, only on PowerPC)
98 Set floating-point exception mode to arg2. Pass
99 PR_FP_EXC_SW_ENABLE to use FPEXC for FP exception enables,
100 PR_FP_EXC_DIV for floating-point divide by zero, PR_FP_EXC_OVF
101 for floating-point overflow, PR_FP_EXC_UND for floating-point
102 underflow, PR_FP_EXC_RES for floating-point inexact result,
103 PR_FP_EXC_INV for floating-point invalid operation,
104 PR_FP_EXC_DISABLED for FP exceptions disabled, PR_FP_EXC_NONRE‐
105 COV for async nonrecoverable exception mode, PR_FP_EXC_ASYNC for
106 async recoverable exception mode, PR_FP_EXC_PRECISE for precise
107 exception mode.
108 PR_GET_FPEXC (since Linux 2.4.21, 2.5.32, only on PowerPC)
110 Return floating-point exception mode, in the location pointed to
111 by (int *) arg2.
112 PR_SET_KEEPCAPS (since Linux 2.2.18)
114 Set the state of the thread's "keep capabilities" flag, which
115 determines whether the threads's permitted capability set is
116 cleared when a change is made to the threads's user IDs such
117 that the threads's real UID, effective UID, and saved set-user-
118 ID all become nonzero when at least one of them previously had
119 the value 0. By default, the permitted capability set is
120 cleared when such a change is made; setting the "keep capabili‐
121 ties" flag prevents it from being cleared. arg2 must be either
122 0 (permitted capabilities are cleared) or 1 (permitted capabili‐
123 ties are kept). (A thread's effective capability set is always
124 cleared when such a credential change is made, regardless of the
125 setting of the "keep capabilities" flag.) The "keep capabili‐
126 ties" value will be reset to 0 on subsequent calls to execve(2).
127 PR_GET_KEEPCAPS (since Linux 2.2.18)
129 Return (as the function result) the current state of the calling
130 threads's "keep capabilities" flag.
131 PR_SET_NAME (since Linux 2.6.9)
133 Set the name of the calling thread, using the value in the loca‐
134 tion pointed to by (char *) arg2. The name can be up to 16
135 bytes long, and should be null-terminated if it contains fewer
136 bytes. This is the same attribute that can be set via
137 pthread_setname_np(3) and retrieved using pthread_getname_np(3).
138 The attribute is likewise accessible via
139 /proc/self/task/[tid]/comm, where tid is the name of the calling
140 thread.
141 PR_GET_NAME (since Linux 2.6.11)
143 Return the name of the calling thread, in the buffer pointed to
144 by (char *) arg2. The buffer should allow space for up to 16
145 bytes; the returned string will be null-terminated if it is
146 shorter than that.
147 PR_SET_NO_NEW_PRIVS (since Linux 3.5)
149 Set the calling process's no_new_privs bit to the value in arg2.
150 With no_new_privs set to 1, execve(2) promises not to grant
151 privileges to do anything that could not have been done without
152 the execve(2) call (for example, rendering the set-user-ID and
153 set-group-ID permission bits, and file capabilities non-func‐
154 tional). Once set, this bit cannot be unset. The setting of
155 this bit is inherited by children created by fork(2) and
156 clone(2), and preserved across execve(2).
157 For more information, see the kernel source file Documenta‐
159 tion/prctl/no_new_privs.txt.
160 PR_GET_NO_NEW_PRIVS (since Linux 3.5)
162 Return the value of the no_new_privs bit for the current
163 process. A value of 0 indicates the regular execve(2) behavior.
164 A value of 1 indicates execve(2) will operate in the privilege-
165 restricting mode described above.
166 PR_SET_PDEATHSIG (since Linux 2.1.57)
168 Set the parent process death signal of the calling process to
169 arg2 (either a signal value in the range 1..maxsig, or 0 to
170 clear). This is the signal that the calling process will get
171 when its parent dies. This value is cleared for the child of a
172 fork(2) and (since Linux 2.4.36 / 2.6.23) when executing a set-
173 user-ID or set-group-ID binary.
174 PR_GET_PDEATHSIG (since Linux 2.3.15)
176 Return the current value of the parent process death signal, in
177 the location pointed to by (int *) arg2.
178 PR_SET_PTRACER (since Linux 3.4)
180 This is meaningful only when the Yama LSM is enabled and in mode
181 1 ("restricted ptrace", visible via /proc/sys/ker‐
182 nel/yama/ptrace_scope). When a "ptracer process ID" is passed
183 in arg2, the caller is declaring that the ptracer process can
184 ptrace(2) the calling process as if it were a direct process
185 ancestor. Each PR_SET_PTRACER operation replaces the previous
186 "ptracer process ID". Employing PR_SET_PTRACER with arg2 set to
187 0 clears the caller's "ptracer process ID". If arg2 is
188 PR_SET_PTRACER_ANY, the ptrace restrictions introduced by Yama
189 are effectively disabled for the calling process.
190 For further information, see the kernel source file Documenta‐
192 tion/security/Yama.txt.
193 PR_SET_SECCOMP (since Linux 2.6.23)
195 Set the secure computing (seccomp) mode for the calling thread,
196 to limit the available system calls. The seccomp mode is
197 selected via arg2. (The seccomp constants are defined in
198 <linux/seccomp.h>.)
199 With arg2 set to SECCOMP_MODE_STRICT the only system calls that
201 the thread is permitted to make are read(2), write(2), _exit(2),
202 and sigreturn(2). Other system calls result in the delivery of
203 a SIGKILL signal. Strict secure computing mode is useful for
204 number-crunching applications that may need to execute untrusted
205 byte code, perhaps obtained by reading from a pipe or socket.
206 This operation is available only if the kernel is configured
207 with CONFIG_SECCOMP enabled.
208 With arg2 set to SECCOMP_MODE_FILTER (since Linux 3.5) the sys‐
210 tem calls allowed are defined by a pointer to a Berkeley Packet
211 Filter passed in arg3. This argument is a pointer to struct
212 sock_fprog; it can be designed to filter arbitrary system calls
213 and system call arguments. This mode is available only if the
214 kernel is configured with CONFIG_SECCOMP_FILTER enabled.
215 If SECCOMP_MODE_FILTER filters permit fork(2), then the seccomp
217 mode is inherited by children created by fork(2); if execve(2)
218 is permitted, then the seccomp mode is preserved across
219 execve(2). If the filters permit prctl() calls, then additional
220 filters can be added; they are run in order until the first non-
221 allow result is seen.
222 For further information, see the kernel source file Documenta‐
224 tion/prctl/seccomp_filter.txt.
225 PR_GET_SECCOMP (since Linux 2.6.23)
227 Return the secure computing mode of the calling thread. If the
228 caller is not in secure computing mode, this operation returns
229 0; if the caller is in strict secure computing mode, then the
230 prctl() call will cause a SIGKILL signal to be sent to the
231 process. If the caller is in filter mode, and this system call
232 is allowed by the seccomp filters, it returns 2. This operation
233 is available only if the kernel is configured with CONFIG_SEC‐
234 COMP enabled.
235 PR_SET_SECUREBITS (since Linux 2.6.26)
237 Set the "securebits" flags of the calling thread to the value
238 supplied in arg2. See capabilities(7).
239 PR_GET_SECUREBITS (since Linux 2.6.26)
241 Return (as the function result) the "securebits" flags of the
242 calling thread. See capabilities(7).
243 PR_GET_TID_ADDRESS (since Linux 3.5)
245 Retrieve the clear_child_tid address set by set_tid_address(2)
246 and the clone(2) CLONE_CHILD_CLEARTID flag, in the location
247 pointed to by (int **) arg2. This feature is available only if
248 the kernel is built with the CONFIG_CHECKPOINT_RESTORE option
249 enabled.
250 PR_SET_TIMERSLACK (since Linux 2.6.28)
252 Set the current timer slack for the calling thread to the
253 nanosecond value supplied in arg2. If arg2 is less than or
254 equal to zero, reset the current timer slack to the thread's
255 default timer slack value. The timer slack is used by the ker‐
256 nel to group timer expirations for the calling thread that are
257 close to one another; as a consequence, timer expirations for
258 the thread may be up to the specified number of nanoseconds late
259 (but will never expire early). Grouping timer expirations can
260 help reduce system power consumption by minimizing CPU wake-ups.
261 The timer expirations affected by timer slack are those set by
263 select(2), pselect(2), poll(2), ppoll(2), epoll_wait(2),
264 epoll_pwait(2), clock_nanosleep(2), nanosleep(2), and futex(2)
265 (and thus the library functions implemented via futexes, includ‐
266 ing pthread_cond_timedwait(3), pthread_mutex_timedlock(3),
267 pthread_rwlock_timedrdlock(3), pthread_rwlock_timedwrlock(3),
268 and sem_timedwait(3)).
269 Timer slack is not applied to threads that are scheduled under a
271 realtime scheduling policy (see sched_setscheduler(2)).
272 Each thread has two associated timer slack values: a "default"
274 value, and a "current" value. The current value is the one that
275 governs grouping of timer expirations. When a new thread is
276 created, the two timer slack values are made the same as the
277 current value of the creating thread. Thereafter, a thread can
278 adjust its current timer slack value via PR_SET_TIMERSLACK (the
279 default value can't be changed). The timer slack values of init
280 (PID 1), the ancestor of all processes, are 50,000 nanoseconds
281 (50 microseconds). The timer slack values are preserved across
282 execve(2).
283 PR_GET_TIMERSLACK (since Linux 2.6.28)
285 Return the current timer slack value of the calling thread.
286 PR_SET_TIMING (since Linux 2.6.0-test4)
288 Set whether to use (normal, traditional) statistical process
289 timing or accurate timestamp-based process timing, by passing
290 PR_TIMING_STATISTICAL or PR_TIMING_TIMESTAMP to arg2. PR_TIM‐
291 ING_TIMESTAMP is not currently implemented (attempting to set
292 this mode will yield the error EINVAL).
293 PR_GET_TIMING (since Linux 2.6.0-test4)
295 Return (as the function result) which process timing method is
296 currently in use.
297 PR_TASK_PERF_EVENTS_DISABLE (since Linux 2.6.31)
299 Disable all performance counters attached to the calling
300 process, regardless of whether the counters were created by this
301 process or another process. Performance counters created by the
302 calling process for other processes are unaffected. For more
303 information on performance counters, see the Linux kernel source
304 file tools/perf/design.txt.
305 Originally called PR_TASK_PERF_COUNTERS_DISABLE; renamed (with
307 same numerical value) in Linux 2.6.32.
308 PR_TASK_PERF_EVENTS_ENABLE (since Linux 2.6.31)
310 The converse of PR_TASK_PERF_EVENTS_DISABLE; enable performance
311 counters attached to the calling process.
312 Originally called PR_TASK_PERF_COUNTERS_ENABLE; renamed in Linux
314 2.6.32.
315 PR_SET_TSC (since Linux 2.6.26, x86 only)
317 Set the state of the flag determining whether the timestamp
318 counter can be read by the process. Pass PR_TSC_ENABLE to arg2
319 to allow it to be read, or PR_TSC_SIGSEGV to generate a SIGSEGV
320 when the process tries to read the timestamp counter.
321 PR_GET_TSC (since Linux 2.6.26, x86 only)
323 Return the state of the flag determining whether the timestamp
324 counter can be read, in the location pointed to by (int *) arg2.
325 PR_SET_UNALIGN
327 (Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
328 PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22) Set
329 unaligned access control bits to arg2. Pass PR_UNALIGN_NOPRINT
330 to silently fix up unaligned user accesses, or PR_UNALIGN_SIGBUS
331 to generate SIGBUS on unaligned user access.
332 PR_GET_UNALIGN
334 (see PR_SET_UNALIGN for information on versions and architec‐
335 tures) Return unaligned access control bits, in the location
336 pointed to by (int *) arg2.
337 PR_MCE_KILL (since Linux 2.6.32)
339 Set the machine check memory corruption kill policy for the cur‐
340 rent thread. If arg2 is PR_MCE_KILL_CLEAR, clear the thread
341 memory corruption kill policy and use the system-wide default.
342 (The system-wide default is defined by /proc/sys/vm/memory_fail‐
343 ure_early_kill; see proc(5).) If arg2 is PR_MCE_KILL_SET, use a
344 thread-specific memory corruption kill policy. In this case,
345 arg3 defines whether the policy is early kill
346 (PR_MCE_KILL_EARLY), late kill (PR_MCE_KILL_LATE), or the sys‐
347 tem-wide default (PR_MCE_KILL_DEFAULT). Early kill means that
348 the thread receives a SIGBUS signal as soon as hardware memory
349 corruption is detected inside its address space. In late kill
350 mode, the process is killed only when it accesses a corrupted
351 page. See sigaction(2) for more information on the SIGBUS sig‐
352 nal. The policy is inherited by children. The remaining unused
353 prctl() arguments must be zero for future compatibility.
354 PR_MCE_KILL_GET (since Linux 2.6.32)
356 Return the current per-process machine check kill policy. All
357 unused prctl() arguments must be zero.
358 PR_SET_MM (since Linux 3.3)
360 Modify certain kernel memory map descriptor fields of the call‐
361 ing process. Usually these fields are set by the kernel and
362 dynamic loader (see ld.so(8) for more information) and a regular
363 application should not use this feature. However, there are
364 cases, such as self-modifying programs, where a program might
365 find it useful to change its own memory map. This feature is
366 available only if the kernel is built with the CONFIG_CHECK‐
367 POINT_RESTORE option enabled. The calling process must have the
368 CAP_SYS_RESOURCE capability. The value in arg2 is one of the
369 options below, while arg3 provides a new value for the option.
370 PR_SET_MM_START_CODE
372 Set the address above which the program text can run.
373 The corresponding memory area must be readable and exe‐
374 cutable, but not writable or sharable (see mprotect(2)
375 and mmap(2) for more information).
376 PR_SET_MM_END_CODE
378 Set the address below which the program text can run.
379 The corresponding memory area must be readable and exe‐
380 cutable, but not writable or sharable.
381 PR_SET_MM_START_DATA
383 Set the address above which initialized and uninitialized
384 (bss) data are placed. The corresponding memory area
385 must be readable and writable, but not executable or
386 sharable.
387 PR_SET_MM_END_DATA
389 Set the address below which initialized and uninitialized
390 (bss) data are placed. The corresponding memory area
391 must be readable and writable, but not executable or
392 sharable.
393 PR_SET_MM_START_STACK
395 Set the start address of the stack. The corresponding
396 memory area must be readable and writable.
397 PR_SET_MM_START_BRK
399 Set the address above which the program heap can be
400 expanded with brk(2) call. The address must be greater
401 than the ending address of the current program data seg‐
402 ment. In addition, the combined size of the resulting
403 heap and the size of the data segment can't exceed the
404 RLIMIT_DATA resource limit (see setrlimit(2)).
405 PR_SET_MM_BRK
407 Set the current brk(2) value. The requirements for the
408 address are the same as for the PR_SET_MM_START_BRK
409 option.
410
412 On success, PR_GET_DUMPABLE, PR_GET_KEEPCAPS, PR_GET_NO_NEW_PRIVS,
413 PR_CAPBSET_READ, PR_GET_TIMING, PR_GET_SECUREBITS, PR_MCE_KILL_GET, and
414 (if it returns) PR_GET_SECCOMP return the nonnegative values described
415 above. All other option values return 0 on success. On error, -1 is
416 returned, and errno is set appropriately.
417
419 EFAULT arg2 is an invalid address.
420 EINVAL The value of option is not recognized.
422 EINVAL option is PR_MCE_KILL or PR_MCE_KILL_GET or PR_SET_MM, and
424 unused prctl() arguments were not specified as zero.
425 EINVAL arg2 is not valid value for this option.
427 EINVAL option is PR_SET_SECCOMP or PR_GET_SECCOMP, and the kernel was
429 not configured with CONFIG_SECCOMP.
430 EINVAL option is PR_SET_MM, and one of the following is true
432 * arg4 or arg5 is nonzero;
434 * arg3 is greater than TASK_SIZE (the limit on the size of the
436 user address space for this architecture);
437 * arg2 is PR_SET_MM_START_CODE, PR_SET_MM_END_CODE,
439 PR_SET_MM_START_DATA, PR_SET_MM_END_DATA, or
440 PR_SET_MM_START_STACK, and the permissions of the correspond‐
441 ing memory area are not as required;
442 * arg2 is PR_SET_MM_START_BRK or PR_SET_MM_BRK, and arg3 is
444 less than or equal to the end of the data segment or speci‐
445 fies a value that would cause the RLIMIT_DATA resource limit
446 to be exceeded.
447 EINVAL option is PR_SET_PTRACER and arg2 is not 0, PR_SET_PTRACER_ANY,
449 or the PID of an existing process.
450 EPERM option is PR_SET_SECUREBITS, and the caller does not have the
452 CAP_SETPCAP capability, or tried to unset a "locked" flag, or
453 tried to set a flag whose corresponding locked flag was set (see
454 capabilities(7)).
455 EPERM option is PR_SET_KEEPCAPS, and the callers's
457 SECURE_KEEP_CAPS_LOCKED flag is set (see capabilities(7)).
458 EPERM option is PR_CAPBSET_DROP, and the caller does not have the
460 CAP_SETPCAP capability.
461 EPERM option is PR_SET_MM, and the caller does not have the
463 CAP_SYS_RESOURCE capability.
464
466 The prctl() system call was introduced in Linux 2.1.57.
467
469 This call is Linux-specific. IRIX has a prctl() system call (also
470 introduced in Linux 2.1.44 as irix_prctl on the MIPS architecture),
471 with prototype
472 ptrdiff_t prctl(int option, int arg2, int arg3);
474 and options to get the maximum number of processes per user, get the
476 maximum number of processors the calling process can use, find out
477 whether a specified process is currently blocked, get or set the maxi‐
478 mum stack size, and so on.
479
481 signal(2), core(5)
482
484 This page is part of release 3.53 of the Linux man-pages project. A
485 description of the project, and information about reporting bugs, can
486 be found at http://www.kernel.org/doc/man-pages/.
487Linux 2013-05-21 PRCTL(2)