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 2017-09-15 "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 .PP
  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 .PP
  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 .PP
  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 Attempts to set a priority outside this range
  99 are silently clamped to the range.
 100 The default priority is 0;
 101 lower values give a process a higher scheduling priority.
 102 .PP
 103 The
 104 .BR getpriority ()
 105 call returns the highest priority (lowest numerical value)
 106 enjoyed by any of the specified processes.
 107 The
 108 .BR setpriority ()
 109 call sets the priorities of all of the specified processes
 110 to the specified value.
 111 .PP
 112 Traditionally, only a privileged process could lower the nice value
 113 (i.e., set a higher priority).
 114 However, since Linux 2.6.12, an unprivileged process can decrease
 115 the nice value of a target process that has a suitable
 116 .BR RLIMIT_NICE
 117 soft limit; see
 118 .BR getrlimit (2)
 119 for details.
 120 .SH RETURN VALUE
 121 On success,
 122 .BR getpriority ()
 123 returns the calling thread's nice value, which may be a negative number.
 124 On error, it returns \-1 and sets
 125 .I errno
 126 to indicate the cause of the error.
 127 Since a successful call to
 128 .BR getpriority ()
 129 can legitimately return the value \-1, it is necessary
 130 to clear the external variable
 131 .I errno
 132 prior to the
 133 call, then check it afterward to determine
 134 if \-1 is an error or a legitimate value.
 135 .PP
 136 .BR setpriority ()
 137 returns 0 on success.
 138 On error, it returns \-1 and sets
 139 .I errno
 140 to indicate the cause of the error.
 141 .SH ERRORS
 142 .TP
 143 .B EINVAL
 144 .I which
 145 was not one of
 146 .BR PRIO_PROCESS ,
 147 .BR PRIO_PGRP ,
 148 or
 149 .BR PRIO_USER .
 150 .TP
 151 .B ESRCH
 152 No process was located using the
 153 .I which
 154 and
 155 .I who
 156 values specified.
 157 .PP
 158 In addition to the errors indicated above,
 159 .BR setpriority ()
 160 may fail if:
 161 .TP
 162 .B EACCES
 163 The caller attempted to set a lower nice value
 164 (i.e., a higher process priority), but did not
 165 have the required privilege (on Linux: did not have the
 166 .B CAP_SYS_NICE
 167 capability).
 168 .TP
 169 .B EPERM
 170 A process was located, but its effective user ID did not match
 171 either the effective or the real user ID of the caller,
 172 and was not privileged (on Linux: did not have the
 173 .B CAP_SYS_NICE
 174 capability).
 175 But see NOTES below.
 176 .SH CONFORMING TO
 177 POSIX.1-2001, POSIX.1-2008,
 178 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
 179 .SH NOTES
 180 For further details on the nice value, see
 181 .BR sched (7).
 182 .PP
 183 .IR Note :
 184 the addition of the "autogroup" feature in Linux 2.6.38 means that
 185 the nice value no longer has its traditional effect in many circumstances.
 186 For details, see
 187 .BR sched (7).
 188 .PP
 189 A child created by
 190 .BR fork (2)
 191 inherits its parent's nice value.
 192 The nice value is preserved across
 193 .BR execve (2).
 194 .PP
 195 The details on the condition for
 196 .B EPERM
 197 depend on the system.
 198 The above description is what POSIX.1-2001 says, and seems to be followed on
 199 all System\ V-like systems.
 200 Linux kernels before 2.6.12 required the real or
 201 effective user ID of the caller to match
 202 the real user of the process \fIwho\fP (instead of its effective user ID).
 203 Linux 2.6.12 and later require
 204 the effective user ID of the caller to match
 205 the real or effective user ID of the process \fIwho\fP.
 206 All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
 207 4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
 208 manner as Linux 2.6.12 and later.
 209 .PP
 210 Including
 211 .I <sys/time.h>
 212 is not required these days, but increases portability.
 213 (Indeed,
 214 .I <sys/resource.h>
 215 defines the
 216 .I rusage
 217 structure with fields of type
 218 .I struct timeval
 219 defined in
 220 .IR <sys/time.h> .)
 221 .\"
 222 .SS C library/kernel differences
 223 Within the kernel, nice values are actually represented
 224 using the range 40..1
 225 (since negative numbers are error codes) and these are the values
 226 employed by the
 227 .BR setpriority ()
 228 and
 229 .BR getpriority ()
 230 system calls.
 231 The glibc wrapper functions for these system calls handle the
 232 translations between the user-land and kernel representations
 233 of the nice value according to the formula
 234 .IR "unice\ =\ 20\ \-\ knice" .
 235 (Thus, the kernel's 40..1 range corresponds to the
 236 range \-20..19 as seen by user space.)
 237 .SH BUGS
 238 According to POSIX, the nice value is a per-process setting.
 239 However, under the current Linux/NPTL implementation of POSIX threads,
 240 the nice value is a per-thread attribute:
 241 different threads in the same process can have different nice values.
 242 Portable applications should avoid relying on the Linux behavior,
 243 which may be made standards conformant in the future.
 244 .SH SEE ALSO
 245 .BR nice (1),
 246 .BR renice (1),
 247 .BR fork (2),
 248 .BR capabilities (7),
 249 .BR sched (7)
 250 .PP
 251 .I Documentation/scheduler/sched-nice-design.txt
 252 in the Linux kernel source tree (since Linux 2.6.23)