man2/getpriority.2

   1 .\" Copyright (c) 1980, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   5 .\"
   6 .\"     @(#)getpriority.2       6.9 (Berkeley) 3/10/91
   7 .\"
   8 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
   9 .\" Modified 1996-07-01 by Andries Brouwer <aeb@cwi.nl>
  10 .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
  11 .\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com>
  12 .\"    Corrected statement under EPERM to clarify privileges required
  13 .\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com>
  14 .\"    Clarified meaning of 0 value for 'who' argument
  15 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  16 .\"
  17 .TH GETPRIORITY 2 2021-08-27 "Linux" "Linux Programmer's Manual"
  18 .SH NAME
  19 getpriority, setpriority \- get/set program scheduling priority
  20 .SH LIBRARY
  21 Standard C library
  22 .RI ( libc ", " \-lc )
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <sys/resource.h>
  26 .PP
  27 .BI "int getpriority(int " which ", id_t " who );
  28 .BI "int setpriority(int " which ", id_t " who ", int " prio );
  29 .fi
  30 .SH DESCRIPTION
  31 The scheduling priority of the process, process group, or user, as
  32 indicated by
  33 .I which
  34 and
  35 .I who
  36 is obtained with the
  37 .BR getpriority ()
  38 call and set with the
  39 .BR setpriority ()
  40 call.
  41 The process attribute dealt with by these system calls is
  42 the same attribute (also known as the "nice" value) that is dealt with by
  43 .BR nice (2).
  44 .PP
  45 The value
  46 .I which
  47 is one of
  48 .BR PRIO_PROCESS ,
  49 .BR PRIO_PGRP ,
  50 or
  51 .BR PRIO_USER ,
  52 and
  53 .I who
  54 is interpreted relative to
  55 .I which
  56 (a process identifier for
  57 .BR PRIO_PROCESS ,
  58 process group
  59 identifier for
  60 .BR PRIO_PGRP ,
  61 and a user ID for
  62 .BR PRIO_USER ).
  63 A zero value for
  64 .I who
  65 denotes (respectively) the calling process, the process group of the
  66 calling process, or the real user ID of the calling process.
  67 .PP
  68 The
  69 .I prio
  70 argument is a value in the range \-20 to 19 (but see NOTES below),
  71 with \-20 being the highest priority and 19 being the lowest priority.
  72 Attempts to set a priority outside this range
  73 are silently clamped to the range.
  74 The default priority is 0;
  75 lower values give a process a higher scheduling priority.
  76 .PP
  77 The
  78 .BR getpriority ()
  79 call returns the highest priority (lowest numerical value)
  80 enjoyed by any of the specified processes.
  81 The
  82 .BR setpriority ()
  83 call sets the priorities of all of the specified processes
  84 to the specified value.
  85 .PP
  86 Traditionally, only a privileged process could lower the nice value
  87 (i.e., set a higher priority).
  88 However, since Linux 2.6.12, an unprivileged process can decrease
  89 the nice value of a target process that has a suitable
  90 .B RLIMIT_NICE
  91 soft limit; see
  92 .BR getrlimit (2)
  93 for details.
  94 .SH RETURN VALUE
  95 On success,
  96 .BR getpriority ()
  97 returns the calling thread's nice value, which may be a negative number.
  98 On error, it returns \-1 and sets
  99 .I errno
 100 to indicate the error.
 101 .PP
 102 Since a successful call to
 103 .BR getpriority ()
 104 can legitimately return the value \-1, it is necessary
 105 to clear
 106 .I errno
 107 prior to the
 108 call, then check
 109 .I errno
 110 afterward to determine
 111 if \-1 is an error or a legitimate value.
 112 .PP
 113 .BR setpriority ()
 114 returns 0 on success.
 115 On failure, it returns \-1 and sets
 116 .I errno
 117 to indicate the error.
 118 .SH ERRORS
 119 .TP
 120 .B EACCES
 121 The caller attempted to set a lower nice value
 122 (i.e., a higher process priority), but did not
 123 have the required privilege (on Linux: did not have the
 124 .B CAP_SYS_NICE
 125 capability).
 126 .TP
 127 .B EINVAL
 128 .I which
 129 was not one of
 130 .BR PRIO_PROCESS ,
 131 .BR PRIO_PGRP ,
 132 or
 133 .BR PRIO_USER .
 134 .TP
 135 .B EPERM
 136 A process was located, but its effective user ID did not match
 137 either the effective or the real user ID of the caller,
 138 and was not privileged (on Linux: did not have the
 139 .B CAP_SYS_NICE
 140 capability).
 141 But see NOTES below.
 142 .TP
 143 .B ESRCH
 144 No process was located using the
 145 .I which
 146 and
 147 .I who
 148 values specified.
 149 .SH STANDARDS
 150 POSIX.1-2001, POSIX.1-2008,
 151 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
 152 .SH NOTES
 153 For further details on the nice value, see
 154 .BR sched (7).
 155 .PP
 156 .IR Note :
 157 the addition of the "autogroup" feature in Linux 2.6.38 means that
 158 the nice value no longer has its traditional effect in many circumstances.
 159 For details, see
 160 .BR sched (7).
 161 .PP
 162 A child created by
 163 .BR fork (2)
 164 inherits its parent's nice value.
 165 The nice value is preserved across
 166 .BR execve (2).
 167 .PP
 168 The details on the condition for
 169 .B EPERM
 170 depend on the system.
 171 The above description is what POSIX.1-2001 says, and seems to be followed on
 172 all System\ V-like systems.
 173 Linux kernels before 2.6.12 required the real or
 174 effective user ID of the caller to match
 175 the real user of the process \fIwho\fP (instead of its effective user ID).
 176 Linux 2.6.12 and later require
 177 the effective user ID of the caller to match
 178 the real or effective user ID of the process \fIwho\fP.
 179 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
 180 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
 181 manner as Linux 2.6.12 and later.
 182 .\"
 183 .SS C library/kernel differences
 184 The getpriority system call returns nice values translated to the range 40..1,
 185 since a negative return value would be interpreted as an error.
 186 The glibc wrapper function for
 187 .BR getpriority ()
 188 translates the value back according to the formula
 189 .I unice\~=\~20\~\-\~knice
 190 (thus, the 40..1 range returned by the kernel
 191 corresponds to the range \-20..19 as seen by user space).
 192 .SH BUGS
 193 According to POSIX, the nice value is a per-process setting.
 194 However, under the current Linux/NPTL implementation of POSIX threads,
 195 the nice value is a per-thread attribute:
 196 different threads in the same process can have different nice values.
 197 Portable applications should avoid relying on the Linux behavior,
 198 which may be made standards conformant in the future.
 199 .SH SEE ALSO
 200 .BR nice (1),
 201 .BR renice (1),
 202 .BR fork (2),
 203 .BR capabilities (7),
 204 .BR sched (7)
 205 .PP
 206 .I Documentation/scheduler/sched\-nice\-design.txt
 207 in the Linux kernel source tree (since Linux 2.6.23)