.\" Clarified meaning of 0 value for 'who' argument
.\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.\" FIXME Oct 2008: Denys Vlasenko is working on a PRIO_THREAD feature that
-.\" is likely to get included in mainline; this will need to be documented.
-.\"
-.TH GETPRIORITY 2 2014-05-10 "Linux" "Linux Programmer's Manual"
+.TH GETPRIORITY 2 2016-12-12 "Linux" "Linux Programmer's Manual"
.SH NAME
getpriority, setpriority \- get/set program scheduling priority
.SH SYNOPSIS
call and set with the
.BR setpriority ()
call.
+The process attribute dealt with by these system calls is
+the same attribute (also known as the "nice" value) that is dealt with by
+.BR nice (2).
The value
.I which
.I who
denotes (respectively) the calling process, the process group of the
calling process, or the real user ID of the calling process.
-.I Prio
-is a value in the range \-20 to 19 (but see the Notes below).
+
+The
+.I prio
+argument is a value in the range \-20 to 19 (but see NOTES below).
+with \-20 being the highest priority and 19 being the lowest priority.
+Attempts to set a priority outside this range
+are silently clamped to the range.
The default priority is 0;
-lower priorities cause more favorable scheduling.
+lower values give a process a higher scheduling priority.
The
.BR getpriority ()
.BR setpriority ()
call sets the priorities of all of the specified processes
to the specified value.
-Only the superuser may lower priorities.
+
+Traditionally, only a privileged process could lower the nice value
+(i.e., set a higher priority).
+However, since Linux 2.6.12, an unprivileged process can decrease
+the nice value of a target process that has a suitable
+.BR RLIMIT_NICE
+soft limit; see
+.BR getrlimit (2)
+for details.
.SH RETURN VALUE
-Since
+On success,
+.BR getpriority ()
+returns the calling thread's nice value, which may be a negative number.
+On error, it returns \-1 and sets
+.I errno
+to indicate the cause of the error.
+Since a successful call to
.BR getpriority ()
can legitimately return the value \-1, it is necessary
to clear the external variable
prior to the
call, then check it afterward to determine
if \-1 is an error or a legitimate value.
-The
+
.BR setpriority ()
-call returns 0 if there is no error, or
-\-1 if there is.
+returns 0 on success.
+On error, it returns \-1 and sets
+.I errno
+to indicate the cause of the error.
.SH ERRORS
.TP
.B EINVAL
may fail if:
.TP
.B EACCES
-The caller attempted to lower a process priority, but did not
+The caller attempted to set a lower nice value
+(i.e., a higher process priority), but did not
have the required privilege (on Linux: did not have the
.B CAP_SYS_NICE
capability).
-Since Linux 2.6.12, this error occurs only if the caller attempts
-to set a process priority outside the range of the
-.B RLIMIT_NICE
-soft resource limit of the target process; see
-.BR getrlimit (2)
-for details.
.TP
.B EPERM
A process was located, but its effective user ID did not match
capability).
But see NOTES below.
.SH CONFORMING TO
-SVr4, 4.4BSD (these function calls first appeared in 4.2BSD),
-POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008,
+SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
.SH NOTES
+For further details on the nice value, see
+.BR sched (7).
+
+.IR Note :
+the addition of the "autogroup" feature in Linux 2.6.38 means that
+the nice value no longer has its traditional effect in many circumstances.
+For details, see
+.BR sched (7).
+
A child created by
.BR fork (2)
inherits its parent's nice value.
The nice value is preserved across
.BR execve (2).
-The degree to which their relative nice value affects the scheduling of
-processes varies across UNIX systems, and,
-on Linux, across kernel versions.
-Starting with kernel 2.6.23, Linux adopted an algorithm that causes
-relative differences in nice values to have a much stronger effect.
-This causes very low nice values (+19) to truly provide little CPU
-to a process whenever there is any other
-higher priority load on the system,
-and makes high nice values (\-20) deliver most of the CPU to applications
-that require it (e.g., some audio applications).
-
The details on the condition for
.B EPERM
depend on the system.
All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same
manner as Linux 2.6.12 and later.
-.LP
-The actual priority range varies between kernel versions.
-Linux before 1.3.36 had \-infinity..15.
-Since kernel 1.3.43, Linux has the range \-20..19.
-On some other systems, the range of nice values is \-20..20.
Including
.I <sys/time.h>
defined in
.IR <sys/time.h> .)
.\"
-.SS C library/kernel ABI differences
+.SS C library/kernel differences
Within the kernel, nice values are actually represented
-using the corresponding range 40..1
+using the range 40..1
(since negative numbers are error codes) and these are the values
employed by the
.BR setpriority ()
translations between the user-land and kernel representations
of the nice value according to the formula
.IR "unice\ =\ 20\ \-\ knice" .
+(Thus, the kernel's 40..1 range corresponds to the
+range \-20..19 as seen by user space.)
.SH BUGS
According to POSIX, the nice value is a per-process setting.
However, under the current Linux/NPTL implementation of POSIX threads,
projects / thirdparty / man-pages.git / blobdiff