.\" Copyright (c) 1980, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)getpriority.2 6.9 (Berkeley) 3/10/91
.\"
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1996-07-01 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
-.\" Modified 2001-10-21 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\" Modified 2001-10-21 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" Corrected statement under EPERM to clarify privileges required
-.\" Modified 2002-06-21 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\" Modified 2002-06-21 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" Clarified meaning of 0 value for 'who' argument
-.\" Modified 2004-05-27 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
-.TH GETPRIORITY 2 2002-06-21 "BSD Man Page" "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
.br
.B #include <sys/resource.h>
.sp
-.BI "int getpriority(int " which ", int " who );
+.BI "int getpriority(int " which ", id_t " who );
.br
-.BI "int setpriority(int " which ", int " who ", int " prio );
+.BI "int setpriority(int " which ", id_t " who ", int " prio );
.SH DESCRIPTION
The scheduling priority of the process, process group, or user, as
indicated by
and
.I who
is obtained with the
-.B getpriority
+.BR getpriority ()
call and set with the
-.B setpriority
+.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
.BR PRIO_PGRP ,
or
.BR PRIO_USER ,
-and
+and
.I who
-is interpreted relative to
+is interpreted relative to
.I which
(a process identifier for
.BR PRIO_PROCESS ,
.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
-.B getpriority
+.BR getpriority ()
call returns the highest priority (lowest numerical value)
-enjoyed by any of the specified processes. The
-.B setpriority
+enjoyed by any of the specified processes.
+The
+.BR setpriority ()
call sets the priorities of all of the specified processes
-to the specified value. Only the superuser may lower priorities.
-.SH "RETURN VALUE"
-Since
-.B getpriority
+to the specified value.
+
+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
+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
.I errno
prior to the
-call, then check it afterwards to determine
-if a \-1 is an error or a legitimate value.
-The
-.B setpriority
-call returns 0 if there is no error, or
-\-1 if there is.
+call, then check it afterward to determine
+if \-1 is an error or a legitimate value.
+
+.BR setpriority ()
+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
.BR PRIO_USER .
.TP
.B ESRCH
-No process was located using the
+No process was located using the
.I which
and
.I who
values specified.
.PP
In addition to the errors indicated above,
-.B setpriority
+.BR setpriority ()
may fail if:
.TP
+.B EACCES
+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).
+.TP
.B EPERM
A process was located, but its effective user ID did not match
either the effective or the real user ID of the caller,
-and (on Linux systems) the caller did not have the
+and was not privileged (on Linux: did not have the
.B CAP_SYS_NICE
-capability.
-.TP
-.B EACCES
-A non superuser attempted to lower a process priority.
+capability).
+But see NOTES below.
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008,
+SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
.SH NOTES
-The details on the condition for EPERM depend on the system.
-The above description is what SUSv3 says, and seems to be followed on
-all SYSV-like systems.
-Linux requires the real or effective user ID of the caller to match
+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 details on the condition for
+.B EPERM
+depend on the system.
+The above description is what POSIX.1-2001 says, and seems to be followed on
+all System\ V-like systems.
+Linux kernels before 2.6.12 required the real or
+effective user ID of the caller to match
the real user of the process \fIwho\fP (instead of its effective user ID).
-All BSD-like systems (SunOS 4.1.3, Ultrix 4.2,
-BSD 4.3, FreeBSD 4.3, OpenBSD-2.5, ...) require
+Linux 2.6.12 and later require
the effective user ID of the caller to match
the real or effective user ID of the process \fIwho\fP.
-.LP
-The actual priority range varies between kernel versions.
-Linux before 1.3.36 had -infinity..15. Linux since 1.3.43 has -20..19,
-and the system call getpriority returns 40..1 for these values
-(since negative numbers are error codes).
-The library call converts N into 20-N.
-.LP
+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.
+
Including
.I <sys/time.h>
is not required these days, but increases portability.
.I struct timeval
defined in
.IR <sys/time.h> .)
-.SH "CONFORMING TO"
-SVr4, 4.4BSD (these function calls first appeared in 4.2BSD).
-.SH "SEE ALSO"
+.\"
+.SS C library/kernel differences
+Within the kernel, nice values are actually represented
+using the range 40..1
+(since negative numbers are error codes) and these are the values
+employed by the
+.BR setpriority ()
+and
+.BR getpriority ()
+system calls.
+The glibc wrapper functions for these system calls handle the
+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,
+the nice value is a per-thread attribute:
+different threads in the same process can have different nice values.
+Portable applications should avoid relying on the Linux behavior,
+which may be made standards conformant in the future.
+.SH SEE ALSO
.BR nice (1),
+.BR renice (1),
.BR fork (2),
.BR capabilities (7),
-.BR renice (8)
+.BR sched (7)
+
+.I Documentation/scheduler/sched-nice-design.txt
+in the Linux kernel source tree (since Linux 2.6.23)
projects / thirdparty / man-pages.git / blobdiff