man5/proc_pid_oom_score_adj.5

   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
   9 /proc/pid/oom_score_adj \- OOM-killer score adjustment
  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)