[thirdparty/man-pages.git] / man / man5 / proc_pid_oom_score_adj.5

.\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\"
.TH proc_pid_oom_score_adj 5 (date) "Linux man-pages (unreleased)"
.SH NAME
/proc/pid/oom_score_adj \- OOM-killer score adjustment
.SH DESCRIPTION
.TP
.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)"
.\" Text taken from Linux 3.7 Documentation/filesystems/proc.txt
This file can be used to adjust the badness heuristic used to select which
process gets killed in out-of-memory conditions.
.IP
The badness heuristic assigns a value to each candidate task ranging from 0
(never kill) to 1000 (always kill) to determine which process is targeted.
The units are roughly a proportion along that range of
allowed memory the process may allocate from,
based on an estimation of its current memory and swap use.
For example, if a task is using all allowed memory,
its badness score will be 1000.
If it is using half of its allowed memory, its score will be 500.
.IP
There is an additional factor included in the badness score: root
processes are given 3% extra memory over other tasks.
.IP
The amount of "allowed" memory depends on the context
in which the OOM-killer was called.
If it is due to the memory assigned to the allocating task's cpuset
being exhausted,
the allowed memory represents the set of mems assigned to that
cpuset (see
.BR cpuset (7)).
If it is due to a mempolicy's node(s) being exhausted,
the allowed memory represents the set of mempolicy nodes.
If it is due to a memory limit (or swap limit) being reached,
the allowed memory is that configured limit.
Finally, if it is due to the entire system being out of memory, the
allowed memory represents all allocatable resources.
.IP
The value of
.I oom_score_adj
is added to the badness score before it
is used to determine which task to kill.
Acceptable values range from \-1000
(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX).
This allows user space to control the preference for OOM-killing,
ranging from always preferring a certain
task or completely disabling it from OOM-killing.
The lowest possible value, \-1000, is
equivalent to disabling OOM-killing entirely for that task,
since it will always report a badness score of 0.
.IP
Consequently, it is very simple for user space to define
the amount of memory to consider for each task.
Setting an
.I oom_score_adj
value of +500, for example,
is roughly equivalent to allowing the remainder of tasks sharing the
same system, cpuset, mempolicy, or memory controller resources
to use at least 50% more memory.
A value of \-500, on the other hand, would be roughly
equivalent to discounting 50% of the task's
allowed memory from being considered as scoring against the task.
.IP
For backward compatibility with previous kernels,
.IR /proc/ pid /oom_adj
can still be used to tune the badness score.
Its value is
scaled linearly with
.IR oom_score_adj .
.IP
Writing to
.IR /proc/ pid /oom_score_adj
or
.IR /proc/ pid /oom_adj
will change the other with its scaled value.
.IP
The
.BR choom (1)
program provides a command-line interface for adjusting the
.I oom_score_adj
value of a running process or a newly executed command.
.SH HISTORY
.TP
.IR /proc/ pid /oom_adj " (since Linux 2.6.11)"
This file can be used to adjust the score used to select which process
should be killed in an out-of-memory (OOM) situation.
The kernel uses this value for a bit-shift operation of the process's
.I oom_score
value:
valid values are in the range \-16 to +15,
plus the special value \-17,
which disables OOM-killing altogether for this process.
A positive score increases the likelihood of this
process being killed by the OOM-killer;
a negative score decreases the likelihood.
.IP
The default value for this file is 0;
a new process inherits its parent's
.I oom_adj
setting.
A process must be privileged
.RB ( CAP_SYS_RESOURCE )
to update this file,
although a process can always increase its own
.I oom_adj
setting (since Linux 2.6.20).
.IP
Since Linux 2.6.36, use of this file is deprecated in favor of
.IR /proc/ pid /oom_score_adj ,
and finally removed in Linux 3.7.
.SH SEE ALSO
.BR proc (5),
.BR proc_pid_oom_score (5)
Commit	Line	Data
21325557 AC	1	.\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
	2	.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
	3	.\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
	4	.\"
	5	.\" SPDX-License-Identifier: GPL-3.0-or-later
	6	.\"
	7	.TH proc_pid_oom_score_adj 5 (date) "Linux man-pages (unreleased)"
	8	.SH NAME
9dfb7cd1	9	/proc/pid/oom_score_adj \- OOM-killer score adjustment
21325557 AC	10	.SH DESCRIPTION
	11	.TP
	12	.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)"
	13	.\" Text taken from Linux 3.7 Documentation/filesystems/proc.txt
	14	This file can be used to adjust the badness heuristic used to select which
	15	process gets killed in out-of-memory conditions.
	16	.IP
	17	The badness heuristic assigns a value to each candidate task ranging from 0
	18	(never kill) to 1000 (always kill) to determine which process is targeted.
	19	The units are roughly a proportion along that range of
	20	allowed memory the process may allocate from,
	21	based on an estimation of its current memory and swap use.
	22	For example, if a task is using all allowed memory,
	23	its badness score will be 1000.
	24	If it is using half of its allowed memory, its score will be 500.
	25	.IP
	26	There is an additional factor included in the badness score: root
	27	processes are given 3% extra memory over other tasks.
	28	.IP
	29	The amount of "allowed" memory depends on the context
	30	in which the OOM-killer was called.
	31	If it is due to the memory assigned to the allocating task's cpuset
	32	being exhausted,
	33	the allowed memory represents the set of mems assigned to that
	34	cpuset (see
	35	.BR cpuset (7)).
	36	If it is due to a mempolicy's node(s) being exhausted,
	37	the allowed memory represents the set of mempolicy nodes.
	38	If it is due to a memory limit (or swap limit) being reached,
	39	the allowed memory is that configured limit.
	40	Finally, if it is due to the entire system being out of memory, the
	41	allowed memory represents all allocatable resources.
	42	.IP
	43	The value of
	44	.I oom_score_adj
	45	is added to the badness score before it
	46	is used to determine which task to kill.
	47	Acceptable values range from \-1000
	48	(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX).
	49	This allows user space to control the preference for OOM-killing,
	50	ranging from always preferring a certain
	51	task or completely disabling it from OOM-killing.
	52	The lowest possible value, \-1000, is
	53	equivalent to disabling OOM-killing entirely for that task,
	54	since it will always report a badness score of 0.
	55	.IP
	56	Consequently, it is very simple for user space to define
	57	the amount of memory to consider for each task.
	58	Setting an
	59	.I oom_score_adj
	60	value of +500, for example,
	61	is roughly equivalent to allowing the remainder of tasks sharing the
	62	same system, cpuset, mempolicy, or memory controller resources
	63	to use at least 50% more memory.
	64	A value of \-500, on the other hand, would be roughly
	65	equivalent to discounting 50% of the task's
	66	allowed memory from being considered as scoring against the task.
	67	.IP
	68	For backward compatibility with previous kernels,
	69	.IR /proc/ pid /oom_adj
	70	can still be used to tune the badness score.
	71	Its value is
	72	scaled linearly with
	73	.IR oom_score_adj .
74	.IP
75	Writing to
76	.IR /proc/ pid /oom_score_adj
77	or
78	.IR /proc/ pid /oom_adj
79	will change the other with its scaled value.
80	.IP
81	The
82	.BR choom (1)
83	program provides a command-line interface for adjusting the
84	.I oom_score_adj
85	value of a running process or a newly executed command.
86	.SH HISTORY
87	.TP
88	.IR /proc/ pid /oom_adj " (since Linux 2.6.11)"
89	This file can be used to adjust the score used to select which process
90	should be killed in an out-of-memory (OOM) situation.
91	The kernel uses this value for a bit-shift operation of the process's
92	.I oom_score
93	value:
94	valid values are in the range \-16 to +15,
95	plus the special value \-17,
96	which disables OOM-killing altogether for this process.
97	A positive score increases the likelihood of this
98	process being killed by the OOM-killer;
99	a negative score decreases the likelihood.
100	.IP
101	The default value for this file is 0;
102	a new process inherits its parent's
103	.I oom_adj
104	setting.
105	A process must be privileged
106	.RB ( CAP_SYS_RESOURCE )
107	to update this file,
108	although a process can always increase its own
109	.I oom_adj
110	setting (since Linux 2.6.20).
111	.IP
112	Since Linux 2.6.36, use of this file is deprecated in favor of
113	.IR /proc/ pid /oom_score_adj ,
114	and finally removed in Linux 3.7.
115	.SH SEE ALSO
116	.BR proc (5),
117	.BR proc_pid_oom_score (5)