diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man2/getpriority.2')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man2/getpriority.2 | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man2/getpriority.2 b/upstream/opensuse-tumbleweed/man2/getpriority.2 new file mode 100644 index 00000000..723d3d49 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man2/getpriority.2 @@ -0,0 +1,209 @@ +.\" Copyright (c) 1980, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)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 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +getpriority, setpriority \- get/set program scheduling priority +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/resource.h> +.PP +.BI "int getpriority(int " which ", id_t " who ); +.BI "int setpriority(int " which ", id_t " who ", int " prio ); +.fi +.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 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). +.PP +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. +.PP +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 values give a process a higher scheduling priority. +.PP +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. +.PP +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 +.B 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 error. +.PP +Since a successful call to +.BR getpriority () +can legitimately return the value \-1, it is necessary +to clear +.I errno +prior to the +call, then check +.I errno +afterward to determine +if \-1 is an error or a legitimate value. +.PP +.BR setpriority () +returns 0 on success. +On failure, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.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 EINVAL +.I which +was not one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER . +.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. +.TP +.B ESRCH +No process was located using the +.I which +and +.I who +values specified. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +.SH NOTES +For further details on the nice value, see +.BR sched (7). +.PP +.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). +.PP +A child created by +.BR fork (2) +inherits its parent's nice value. +The nice value is preserved across +.BR execve (2). +.PP +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 Linux 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. +.\" +.SS C library/kernel differences +The getpriority system call returns nice values translated to the range 40..1, +since a negative return value would be interpreted as an error. +The glibc wrapper function for +.BR getpriority () +translates the value back according to the formula +.I unice\~=\~20\~\-\~knice +(thus, the 40..1 range returned by the kernel +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) +.PP +.I Documentation/scheduler/sched\-nice\-design.txt +in the Linux kernel source tree (since Linux 2.6.23) |