1.\" $OpenBSD: getpriority.2,v 1.15 2015/09/10 17:55:21 schwarze Exp $ 2.\" $NetBSD: getpriority.2,v 1.4 1995/02/27 12:33:15 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)getpriority.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: September 10 2015 $ 34.Dt GETPRIORITY 2 35.Os 36.Sh NAME 37.Nm getpriority , 38.Nm setpriority 39.Nd get/set process scheduling priority 40.Sh SYNOPSIS 41.In sys/resource.h 42.Ft int 43.Fn getpriority "int which" "id_t who" 44.Ft int 45.Fn setpriority "int which" "id_t who" "int prio" 46.Sh DESCRIPTION 47The scheduling priority of the process, process group, or user, 48as indicated by 49.Fa which 50and 51.Fa who 52is obtained with the 53.Fn getpriority 54call and set with the 55.Fn setpriority 56call. 57.Fa which 58is one of 59.Dv PRIO_PROCESS , 60.Dv PRIO_PGRP , 61or 62.Dv PRIO_USER , 63and 64.Fa who 65is interpreted relative to 66.Fa which 67(a process identifier for 68.Dv PRIO_PROCESS , 69process group identifier for 70.Dv PRIO_PGRP , 71and a user ID for 72.Dv PRIO_USER ) . 73A zero value of 74.Fa who 75denotes the current process, process group, or user. 76.Fa prio 77is a value in the range \-20 to 20. 78The default priority is 0; lower priorities cause more favorable scheduling. 79.Pp 80The 81.Fn getpriority 82call returns the highest priority (lowest numerical value) 83enjoyed by any of the specified processes. 84The 85.Fn setpriority 86call sets the priorities of all of the specified processes 87to the specified value. 88Priority values outside the range \-20 to 20 are truncated to the 89appropriate limit. 90Only the superuser may lower priorities. 91.Sh RETURN VALUES 92Since 93.Fn getpriority 94can legitimately return the value \-1, it is necessary 95to clear the external variable 96.Va errno 97prior to the 98call, then check it afterward to determine 99if a \-1 is an error or a legitimate value. 100The 101.Fn setpriority 102call returns 0 if there is no error, or 103\-1 if there is. 104.Sh ERRORS 105.Fn getpriority 106and 107.Fn setpriority 108will fail if: 109.Bl -tag -width Er 110.It Bq Er ESRCH 111No process was located using the 112.Fa which 113and 114.Fa who 115values specified. 116.It Bq Er EINVAL 117.Fa which 118was not one of 119.Dv PRIO_PROCESS , 120.Dv PRIO_PGRP , 121or 122.Dv PRIO_USER . 123.El 124.Pp 125In addition, 126.Fn setpriority 127will fail if: 128.Bl -tag -width Er 129.It Bq Er EPERM 130A process was located, but neither its effective nor real user 131ID matched the effective user ID of the caller. 132.It Bq Er EACCES 133A non-superuser attempted to lower a process priority. 134.El 135.Sh SEE ALSO 136.Xr nice 1 , 137.Xr fork 2 , 138.Xr renice 8 139.Sh STANDARDS 140The 141.Fn getpriority 142and 143.Fn setpriority 144functions conform to 145.St -p1003.1-2008 . 146.Sh HISTORY 147The predecessor of these functions, the former 148.Fn nice 149system call, appeared in 150.At v3 151and was removed in 152.Bx 4.3 Reno . 153The 154.Fn getpriority 155and 156.Fn setpriority 157system calls appeared in 158.Bx 4.1c . 159