]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/prctl.2
Changes: Ready for 3.47
[thirdparty/man-pages.git] / man2 / prctl.2
CommitLineData
fea681da
MK
1.\" Hey Emacs! This file is -*- nroff -*- source.
2.\"
3.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl)
73d3ac53 4.\" and Copyright (C) 2002, 2006, 2008, 2012, 2013 Michael Kerrisk <mtk.manpages@gmail.com>
af5f9508 5.\" and Copyright Guillem Jover <guillem@hadrons.org>
fea681da
MK
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.
c13182ef 15.\"
fea681da
MK
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.
c13182ef 23.\"
fea681da
MK
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
c13182ef 29.\" Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
fea681da 30.\" PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
e87fdd92
MK
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
8ab8b43f
MK
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
bc02b3ea 40.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL
06afe673 41.\" 2012-04 Cyrill Gorcunov, Document PR_SET_MM
bc02b3ea
MK
42.\" 2012-04-25 Michael Kerrisk, Document PR_TASK_PERF_EVENTS_DISABLE and
43.\" PR_TASK_PERF_EVENTS_ENABLE
34447828 44.\" 2012-09-20 Kees Cook, update PR_SET_SECCOMP for mode 2
f83fe154 45.\" 2012-09-20 Kees Cook, document PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS
934487a0
MK
46.\" 2012-10-25 Michael Kerrisk, Document PR_SET_TIMERSLACK and
47.\" PR_GET_TIMERSLACK
491b2e75 48.\" 2013-01-10 Kees Cook, document PR_SET_PTRACER
73d3ac53 49.\" 2012-02-04 Michael kerrisk, document PR_{SET,GET}_CHILD_SUBREAPER
fea681da 50.\"
e14baeeb 51.\"
73d3ac53 52.TH PRCTL 2 2013-02-08 "Linux" "Linux Programmer's Manual"
fea681da
MK
53.SH NAME
54prctl \- operations on a process
55.SH SYNOPSIS
521bf584 56.nf
fea681da
MK
57.B #include <sys/prctl.h>
58.sp
521bf584
MK
59.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
60.BI " unsigned long " arg4 ", unsigned long " arg5 );
61.fi
fea681da 62.SH DESCRIPTION
e511ffb6 63.BR prctl ()
fea681da 64is called with a first argument describing what to do
1a329b56 65(with values defined in \fI<linux/prctl.h>\fP), and further
c4bb193f 66arguments with a significance depending on the first one.
fea681da
MK
67The first argument can be:
68.TP
2e781e20 69.BR PR_CAPBSET_READ " (since Linux 2.6.25)"
8ab8b43f
MK
70Return (as the function result) 1 if the capability specified in
71.I arg2
72is in the calling thread's capability bounding set,
73or 0 if it is not.
74(The capability constants are defined in
75.IR <linux/capability.h> .)
76The capability bounding set dictates
77whether the process can receive the capability through a
2914a14d 78file's permitted capability set on a subsequent call to
8ab8b43f
MK
79.BR execve (2).
80
81If the capability specified in
82.I arg2
83is not valid, then the call fails with the error
84.BR EINVAL .
85.TP
86.BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
87If the calling thread has the
88.B CAP_SETPCAP
89capability, then drop the capability specified by
90.I arg2
91from the calling thread's capability bounding set.
92Any children of the calling thread will inherit the newly
93reduced bounding set.
94
95The call fails with the error:
96.B EPERM
2914a14d 97if the calling thread does not have the
8ab8b43f
MK
98.BR CAP_SETPCAP ;
99.BR EINVAL
100if
101.I arg2
102does not represent a valid capability; or
103.BR EINVAL
104if file capabilities are not enabled in the kernel,
105in which case bounding sets are not supported.
73d3ac53
MK
106
107.TP
108.BR PR_SET_CHILD_SUBREAPER " (since Linux 3.4)"
109.\" commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b
110If
111.I arg2
112is nonzero,
113set the "child subreaper" attribute of the calling process;
114if
115.I arg2
116is zero, unset the attribute.
117When a process is marked as a child subreaper,
118all of the children that it creates, and their descendants,
119will be marked as having a subreaper.
120In effect, a subreaper fulfills the role of
121.BR init (1)
122for its descendant processes.
123Upon termination of a process
124that is orphaned (i.e., its immediate parent has already terminated)
125and marked as having a subreaper,
126the nearest still living ancestor subreaper
127will receive a
128.BR SIGCHLD
129signal and be able to
130.BR wait (2)
131on the process to discover its termination status.
132
133.TP
134.BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)"
135Return the "child subreaper" setting of the caller,
136in the location pointed to by
137.IR "(int\ *) arg2" .
138
8ab8b43f 139.TP
88989295
MK
140.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
141Set the state of the flag determining whether core dumps are produced
6f620318 142for the calling process upon delivery of a signal whose default behavior is
88989295 143to produce a core dump.
6f620318 144(Normally, this flag is set for a process by default, but it is cleared
88989295
MK
145when a set-user-ID or set-group-ID program is executed and also by
146various system calls that manipulate process UIDs and GIDs).
147In kernels up to and including 2.6.12,
8ab8b43f 148.I arg2
88989295
MK
149must be either 0 (process is not dumpable) or 1 (process is dumpable).
150Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
151which caused any binary which normally would not be dumped
152to be dumped readable by root only;
153for security reasons, this feature has been removed.
154.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
155.\" Subject: Fix prctl privilege escalation (CVE-2006-2451)
156.\" From: Marcel Holtmann <marcel () holtmann ! org>
157.\" Date: 2006-07-12 11:12:00
158(See also the description of
159.I /proc/sys/fs/suid_dumpable
160in
161.BR proc (5).)
cadcf1b1 162Processes that are not dumpable can not be attached via
6fdbc779 163.BR ptrace (2)
cadcf1b1 164.BR PTRACE_ATTACH .
64536a1b 165.TP
88989295
MK
166.BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
167Return (as the function result) the current state of the calling
168process's dumpable flag.
169.\" Since Linux 2.6.13, the dumpable flag can have the value 2,
170.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
c7094399 171.\" flags has a nonzero value. This was fixed in 2.6.14.
64536a1b 172.TP
8ab8b43f 173.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
c13182ef 174Set the endian-ness of the calling process to the value given
64536a1b 175in \fIarg2\fP, which should be one of the following:
8ab8b43f 176.\" Respectively 0, 1, 2
64536a1b
MK
177.BR PR_ENDIAN_BIG ,
178.BR PR_ENDIAN_LITTLE ,
179or
0daa9e92 180.B PR_ENDIAN_PPC_LITTLE
64536a1b 181(PowerPC pseudo little endian).
e87fdd92 182.TP
8ab8b43f
MK
183.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
184Return the endian-ness of the calling process,
185in the location pointed to by
186.IR "(int\ *) arg2" .
187.TP
8ab8b43f 188.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
e87fdd92
MK
189Set floating-point emulation control bits to \fIarg2\fP.
190Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
8bd58774
MK
191\fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
192.B SIGFPE
193instead.
e87fdd92 194.TP
8ab8b43f
MK
195.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
196Return floating-point emulation control bits,
197in the location pointed to by
198.IR "(int\ *) arg2" .
e87fdd92 199.TP
8ab8b43f 200.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
1c44bd5b
MK
201Set floating-point exception mode to \fIarg2\fP.
202Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
c45bd688
MK
203\fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
204\fBPR_FP_EXC_OVF\fP for floating-point overflow,
205\fBPR_FP_EXC_UND\fP for floating-point underflow,
206\fBPR_FP_EXC_RES\fP for floating-point inexact result,
207\fBPR_FP_EXC_INV\fP for floating-point invalid operation,
e87fdd92 208\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
b28f6e56 209\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
e87fdd92
MK
210\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
211\fBPR_FP_EXC_PRECISE\fP for precise exception mode.
212.TP
8ab8b43f
MK
213.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
214Return floating-point exception mode,
215in the location pointed to by
216.IR "(int\ *) arg2" .
217.TP
88989295
MK
218.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
219Set the state of the thread's "keep capabilities" flag,
028cb080
MK
220which determines whether the threads's permitted
221capability set is cleared when a change is made to the threads's user IDs
88989295 222such that the threads's real UID, effective UID, and saved set-user-ID
c7094399 223all become nonzero when at least one of them previously had the value 0.
028cb080
MK
224By default, the permitted capability set is cleared when such a change is made;
225setting the "keep capabilities" flag prevents it from being cleared.
88989295 226.I arg2
028cb080
MK
227must be either 0 (permitted capabilities are cleared)
228or 1 (permitted capabilities are kept).
229(A thread's
230.I effective
231capability set is always cleared when such a credential change is made,
232regardless of the setting of the "keep capabilities" flag.)
233The "keep capabilities" value will be reset to 0 on subsequent calls to
88989295
MK
234.BR execve (2).
235.TP
236.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
237Return (as the function result) the current state of the calling threads's
238"keep capabilities" flag.
239.TP
240.BR PR_SET_NAME " (since Linux 2.6.9)"
f49202ae 241Set the process name for the calling thread,
88989295
MK
242using the value in the location pointed to by
243.IR "(char\ *) arg2" .
244The name can be up to 16 bytes long,
245.\" TASK_COMM_LEN in include/linux/sched.h
bd74a873 246and should be null-terminated if it contains fewer bytes.
88989295
MK
247.TP
248.BR PR_GET_NAME " (since Linux 2.6.11)"
f49202ae 249Return the name for the calling thread,
88989295
MK
250in the buffer pointed to by
251.IR "(char\ *) arg2" .
252The buffer should allow space for up to 16 bytes;
bd74a873 253the returned string will be null-terminated if it is shorter than that.
88989295 254.TP
f83fe154 255.BR PR_SET_NO_NEW_PRIVS " (since Linux 3.5)"
0fcc276f
MK
256Set the calling process's
257.I no_new_privs
258bit to the value in
259.IR arg2 .
260With
b1df3071 261.I no_new_privs
0fcc276f
MK
262set to 1,
263.BR execve (2)
b1df3071
MK
264promises not to grant privileges to do anything
265that could not have been done without the
0fcc276f 266.BR execve (2)
b1df3071
MK
267call (for example,
268rendering the set-user-ID and set-group-ID permission bits,
269and file capabilities non-functional).
270Once set, this bit cannot be unset.
271The setting of this bit is inherited by children created by
272.BR fork (2)
0fcc276f 273and
b1df3071
MK
274.BR clone (2),
275and preserved across
276.BR execve (2).
19593937
MK
277
278For more information, see the kernel source file
279.IR Documentation/prctl/no_new_privs.txt .
f83fe154
KC
280.TP
281.BR PR_GET_NO_NEW_PRIVS " (since Linux 3.5)"
0fcc276f
MK
282Return the value of the
283.I no_new_privs
284bit for the current process.
285A value of 0 indicates the regular
286.BR execve (2)
287behavior.
288A value of 1 indicates
289.BR execve (2)
b1df3071 290will operate in the privilege-restricting mode described above.
f83fe154 291.TP
88989295
MK
292.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
293Set the parent process death signal
294of the calling process to \fIarg2\fP (either a signal value
295in the range 1..maxsig, or 0 to clear).
296This is the signal that the calling process will get when its
297parent dies.
298This value is cleared for the child of a
c7c7235c 299.BR fork (2)
46b7f60e 300and (since Linux 2.4.36 / 2.6.23)
f49202ae 301when executing a set-user-ID or set-group-ID binary.
88989295
MK
302.TP
303.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
304Return the current value of the parent process death signal,
305in the location pointed to by
306.IR "(int\ *) arg2" .
307.TP
491b2e75 308.BR PR_SET_PTRACER " (since Linux 3.4)"
ff03be9a
MK
309.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb
310.\" commit bf06189e4d14641c0148bea16e9dd24943862215
491b2e75
KC
311This is only meaningful when the Yama LSM is enabled and in mode 1
312("restricted ptrace", visible via
313.IR /proc/sys/kernel/yama/ptrace_scope ).
2c7d476b
MK
314When a "ptracer process ID" is passed in \fIarg2\fP,
315the caller is declaring that the ptracer process can
316.BR ptrace (2)
317the calling process as if it were a direct process ancestor.
9f4cec52
MK
318Each
319.B PR_SET_PTRACER
320operation replaces the previous "ptracer process ID".
2c7d476b
MK
321Employing
322.B PR_SET_PTRACER
323with
324.I arg2
325set to 0 clears the caller's "ptracer process ID".
326If
327.I arg2
328is
491b2e75
KC
329.BR PR_SET_PTRACER_ANY,
330the ptrace restrictions introduced by Yama are effectively disabled for the
2c7d476b 331calling process.
491b2e75
KC
332
333For further information, see the kernel source file
334.IR Documentation/security/Yama.txt .
335.TP
8ab8b43f
MK
336.BR PR_SET_SECCOMP " (since Linux 2.6.23)"
337.\" See http://thread.gmane.org/gmane.linux.kernel/542632
338.\" [PATCH 0 of 2] seccomp updates
339.\" andrea@cpushare.com
d6ef3d57
MK
340Set the secure computing (seccomp) mode for the calling thread, to limit
341the available system calls.
34447828
KC
342The seccomp mode is selected via
343.IR arg2 .
344(The seccomp constants are defined in
345.IR <linux/seccomp.h> .)
346
347With
8ab8b43f 348.IR arg2
34447828
KC
349set to
350.BR SECCOMP_MODE_STRICT
8ab8b43f
MK
351the only system calls that the thread is permitted to make are
352.BR read (2),
353.BR write (2),