man2/getpriority.2

   1 .\" Copyright (c) 1980, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)getpriority.2       6.9 (Berkeley) 3/10/91
  35 .\"
  36 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  37 .\" Modified 1996-07-01 by Andries Brouwer <aeb@cwi.nl>
  38 .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
  39 .\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com>
  40 .\"    Corrected statement under EPERM to clarify privileges required
  41 .\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com>
  42 .\"    Clarified meaning of 0 value for 'who' argument
  43 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
  44 .\"
  45 .TH GETPRIORITY 2 2016-07-17 "Linux" "Linux Programmer's Manual"
  46 .SH NAME
  47 getpriority, setpriority \- get/set program scheduling priority
  48 .SH SYNOPSIS
  49 .B #include <sys/time.h>
  50 .br
  51 .B #include <sys/resource.h>
  52 .sp
  53 .BI "int getpriority(int " which ", id_t " who );
  54 .br
  55 .BI "int setpriority(int " which ", id_t " who ", int " prio );
  56 .SH DESCRIPTION
  57 The scheduling priority of the process, process group, or user, as
  58 indicated by
  59 .I which
  60 and
  61 .I who
  62 is obtained with the
  63 .BR getpriority ()
  64 call and set with the
  65 .BR setpriority ()
  66 call.
  67 The process attribute dealt with by these system calls is
  68 the same attribute (also known as the "nice" value) that is dealt with by
  69 .BR nice (2).
  70
  71 The value
  72 .I which
  73 is one of
  74 .BR PRIO_PROCESS ,
  75 .BR PRIO_PGRP ,
  76 or
  77 .BR PRIO_USER ,
  78 and
  79 .I who
  80 is interpreted relative to
  81 .I which
  82 (a process identifier for
  83 .BR PRIO_PROCESS ,
  84 process group
  85 identifier for
  86 .BR PRIO_PGRP ,
  87 and a user ID for
  88 .BR PRIO_USER ).
  89 A zero value for
  90 .I who
  91 denotes (respectively) the calling process, the process group of the
  92 calling process, or the real user ID of the calling process.
  93
  94 The
  95 .I prio
  96 argument is a value in the range \-20 to 19 (but see NOTES below).
  97 with \-20 being the highest priority and 19 being the lowest priority.
  98 The default priority is 0;
  99 lower values give a process a higher scheduling priority.
 100
 101 The
 102 .BR getpriority ()
 103 call returns the highest priority (lowest numerical value)
 104 enjoyed by any of the specified processes.
 105 The
 106 .BR setpriority ()
 107 call sets the priorities of all of the specified processes
 108 to the specified value.
 109
 110 Traditionally, only a privileged process could lower the nice value
 111 (i.e., set a higher priority).
 112 However, since Linux 2.6.12, an unprivileged process can decrease
 113 the nice value of a target process that has a suitable
 114 .BR RLIMIT_NICE
 115 soft limit; see
 116 .BR getrlimit (2)
 117 for details.
 118 .SH RETURN VALUE
 119 Since
 120 .BR getpriority ()
 121 can legitimately return the value \-1, it is necessary
 122 to clear the external variable
 123 .I errno
 124 prior to the
 125 call, then check it afterward to determine
 126 if \-1 is an error or a legitimate value.
 127 The
 128 .BR setpriority ()
 129 call returns 0 if there is no error, or
 130 \-1 if there is.
 131 .SH ERRORS
 132 .TP
 133 .B EINVAL
 134 .I which
 135 was not one of
 136 .BR PRIO_PROCESS ,
 137 .BR PRIO_PGRP ,
 138 or
 139 .BR PRIO_USER .
 140 .TP
 141 .B ESRCH
 142 No process was located using the
 143 .I which
 144 and
 145 .I who
 146 values specified.
 147 .PP
 148 In addition to the errors indicated above,
 149 .BR setpriority ()
 150 may fail if:
 151 .TP
 152 .B EACCES
 153 The caller attempted to set a lower nice value
 154 (i.e., a higher process priority), but did not
 155 have the required privilege (on Linux: did not have the
 156 .B CAP_SYS_NICE
 157 capability).
 158 .TP
 159 .B EPERM
 160 A process was located, but its effective user ID did not match
 161 either the effective or the real user ID of the caller,
 162 and was not privileged (on Linux: did not have the
 163 .B CAP_SYS_NICE
 164 capability).
 165 But see NOTES below.
 166 .SH CONFORMING TO
 167 POSIX.1-2001, POSIX.1-2008,
 168 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
 169 .SH NOTES
 170 A child created by
 171 .BR fork (2)
 172 inherits its parent's nice value.
 173 The nice value is preserved across
 174 .BR execve (2).
 175
 176 The degree to which their relative nice value affects the scheduling of
 177 processes varies across UNIX systems, and,
 178 on Linux, across kernel versions.
 179 Starting with kernel 2.6.23, Linux adopted an algorithm that causes
 180 relative differences in nice values to have a much stronger effect.
 181 This causes very low nice values (+19) to truly provide little CPU
 182 to a process whenever there is any other
 183 higher priority load on the system,
 184 and makes high nice values (\-20) deliver most of the CPU to applications
 185 that require it (e.g., some audio applications).
 186
 187 The details on the condition for
 188 .B EPERM
 189 depend on the system.
 190 The above description is what POSIX.1-2001 says, and seems to be followed on
 191 all System\ V-like systems.
 192 Linux kernels before 2.6.12 required the real or
 193 effective user ID of the caller to match
 194 the real user of the process \fIwho\fP (instead of its effective user ID).
 195 Linux 2.6.12 and later require
 196 the effective user ID of the caller to match
 197 the real or effective user ID of the process \fIwho\fP.
 198 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
 199 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
 200 manner as Linux 2.6.12 and later.
 201 .LP
 202 The actual priority range varies between kernel versions.
 203 Linux before 1.3.36 had \-infinity..15.
 204 Since kernel 1.3.43, Linux has the range \-20..19.
 205 On some other systems, the range of nice values is \-20..20.
 206
 207 Including
 208 .I <sys/time.h>
 209 is not required these days, but increases portability.
 210 (Indeed,
 211 .I <sys/resource.h>
 212 defines the
 213 .I rusage
 214 structure with fields of type
 215 .I struct timeval
 216 defined in
 217 .IR <sys/time.h> .)
 218 .\"
 219 .SS C library/kernel differences
 220 Within the kernel, nice values are actually represented
 221 using the range 40..1
 222 (since negative numbers are error codes) and these are the values
 223 employed by the
 224 .BR setpriority ()
 225 and
 226 .BR getpriority ()
 227 system calls.
 228 The glibc wrapper functions for these system calls handle the
 229 translations between the user-land and kernel representations
 230 of the nice value according to the formula
 231 .IR "unice\ =\ 20\ \-\ knice" .
 232 (Thus, the kernel's 40..1 range corresponds to the
 233 range \-20..19 as seen by user space.)
 234 .SH BUGS
 235 According to POSIX, the nice value is a per-process setting.
 236 However, under the current Linux/NPTL implementation of POSIX threads,
 237 the nice value is a per-thread attribute:
 238 different threads in the same process can have different nice values.
 239 Portable applications should avoid relying on the Linux behavior,
 240 which may be made standards conformant in the future.
 241 .SH SEE ALSO
 242 .BR nice (1),
 243 .BR renice (1),
 244 .BR fork (2),
 245 .BR capabilities (7),
 246 .BR sched (7)
 247
 248 .I Documentation/scheduler/sched-nice-design.txt
 249 in the Linux kernel source tree (since Linux 2.6.23)