| .\" 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: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" 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@gmail.com> |
| .\" Corrected statement under EPERM to clarify privileges required |
| .\" 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@gmail.com> |
| .\" |
| .TH GETPRIORITY 2 2015-07-23 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| getpriority, setpriority \- get/set program scheduling priority |
| .SH SYNOPSIS |
| .B #include <sys/time.h> |
| .br |
| .B #include <sys/resource.h> |
| .sp |
| .BI "int getpriority(int " which ", id_t " who ); |
| .br |
| .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 |
| .I which |
| and |
| .I who |
| is obtained with the |
| .BR getpriority () |
| call and set with the |
| .BR setpriority () |
| call. |
| |
| The value |
| .I which |
| is one of |
| .BR PRIO_PROCESS , |
| .BR PRIO_PGRP , |
| or |
| .BR PRIO_USER , |
| and |
| .I who |
| is interpreted relative to |
| .I which |
| (a process identifier for |
| .BR PRIO_PROCESS , |
| process group |
| identifier for |
| .BR PRIO_PGRP , |
| and a user ID for |
| .BR PRIO_USER ). |
| A zero value for |
| .I who |
| denotes (respectively) the calling process, the process group of the |
| calling process, or the real user ID of the calling process. |
| The |
| .I prio |
| argument is a value in the range \-20 to 19 (but see NOTES below). |
| The default priority is 0; |
| lower priorities cause more favorable scheduling. |
| |
| The |
| .BR getpriority () |
| call returns the highest priority (lowest numerical value) |
| 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 |
| .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 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. |
| .SH ERRORS |
| .TP |
| .B EINVAL |
| .I which |
| was not one of |
| .BR PRIO_PROCESS , |
| .BR PRIO_PGRP , |
| or |
| .BR PRIO_USER . |
| .TP |
| .B ESRCH |
| No process was located using the |
| .I which |
| and |
| .I who |
| values specified. |
| .PP |
| In addition to the errors indicated above, |
| .BR setpriority () |
| may fail if: |
| .TP |
| .B EACCES |
| The caller attempted to lower a 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 |
| either the effective or the real user ID of the caller, |
| and was not privileged (on Linux: did not have the |
| .B CAP_SYS_NICE |
| 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 |
| 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. |
| 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). |
| 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. |
| 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> |
| is not required these days, but increases portability. |
| (Indeed, |
| .I <sys/resource.h> |
| defines the |
| .I rusage |
| structure with fields of type |
| .I struct timeval |
| defined in |
| .IR <sys/time.h> .) |
| .\" |
| .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 sched (7) |
| |
| .I Documentation/scheduler/sched-nice-design.txt |
| in the Linux kernel source tree (since Linux 2.6.23) |