1.\" $NetBSD: getpriority.2,v 1.4 1995/02/27 12:33:15 cgd Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getpriority.2 8.1 (Berkeley) 6/4/93 35.\" 36.Dd June 4, 1993 37.Dt GETPRIORITY 2 38.Os BSD 4 39.Sh NAME 40.Nm getpriority , 41.Nm setpriority 42.Nd get/set program scheduling priority 43.Sh SYNOPSIS 44.Fd #include <sys/resource.h> 45.Ft int 46.Fo getpriority 47.Fa "int which" 48.Fa "id_t who" 49.Fc 50.Ft int 51.Fo setpriority 52.Fa "int which" 53.Fa "id_t who" 54.Fa "int prio" 55.Fc 56.Sh DESCRIPTION 57The scheduling priority of the process, process group, or user as indicated by 58.Fa which 59and 60.Fa who 61is obtained with the 62.Fn getpriority 63call and set with the 64.Fn setpriority 65call. 66.Fa Which 67is one of 68.Dv PRIO_PROCESS , 69.Dv PRIO_PGRP , 70or 71.Dv PRIO_USER , 72and 73.Fa who 74is interpreted relative to 75.Fa which 76(a process identifier for 77.Dv PRIO_PROCESS , 78process group 79identifier for 80.Dv PRIO_PGRP , 81and a user ID for 82.Dv PRIO_USER ) . 83A zero value of 84.Fa who 85denotes the current process, process group, or user. 86.Fa prio 87is a value in the range -20 to 20. The default priority is 0; 88lower priorities cause more favorable scheduling. 89.Pp 90The 91.Fn getpriority 92call returns the highest priority (lowest numerical value) 93enjoyed by any of the specified processes. 94The 95.Fn setpriority 96call sets the priorities of all of the specified processes 97to the specified value. Only the super-user may lower priorities. 98.Pp 99Additionally, the current thread or process can be placed in a background state 100by specifying PRIO_DARWIN_THREAD or PRIO_DARWIN_PROCESS for 101.Fa which . 102Only a value of zero (the current thread or process) is supported for 103.Fa who 104when setting or getting background state. 105.Fa prio 106is either 0 (to remove current thread from background status) or PRIO_DARWIN_BG 107(to set current thread into background state). 108When a thread or process is in a background state the scheduling priority is set 109to the lowest value, disk IO is throttled (with behavior similar to using 110.Xr setiopolicy_np 3 111to set a throttleable policy), and network IO is throttled for 112any sockets opened after going into background state. Any previously opened 113sockets are not affected. 114The 115.Fn getpriority 116call returns 0 when current thread or process is not in background state or 1 117when the current thread is in background state. Any thread or process can set 118itself into background state. 119.Sh RETURN VALUES 120Since 121.Fn getpriority 122can legitimately return the value -1, it is necessary 123to clear the external variable 124.Va errno 125prior to the 126call, then check it afterward to determine 127if a -1 is an error or a legitimate value. 128The 129.Fn setpriority 130call returns 0 if there is no error, or 131-1 if there is. 132.Sh ERRORS 133.Fn getpriority 134and 135.Fn setpriority 136will fail if: 137.Bl -tag -width Er 138.\" ========== 139.It Bq Er EINVAL 140.Fa Which 141is not one of 142.Dv PRIO_PROCESS , 143.Dv PRIO_PGRP , 144.Dv PRIO_USER , 145.Dv PRIO_DARWIN_THREAD , 146or 147.Dv PRIO_DARWIN_PROCESS . 148.\" ========== 149.It Bq Er EINVAL 150.Fa Who 151is not a valid process, process group, or user ID. 152.\" ========== 153.It Bq Er EINVAL 154.Fa Who 155is not 0 when 156.Fa which 157is 158.Dv PRIO_DARWIN_THREAD 159or 160.Dv PRIO_DARWIN_PROCESS . 161.\" ========== 162.It Bq Er ESRCH 163No process can be located using the 164.Fa which 165and 166.Fa who 167values specified. 168.El 169.Pp 170.Bl -tag -width Er 171In addition to the errors indicated above, 172.Fn setpriority 173will fail if: 174.\" ========== 175.It Bq Er EACCES 176A non super-user attempts to lower a process priority. 177.\" ========== 178.It Bq Er EPERM 179A process is located, 180but neither its effective nor real user ID 181matches the effective user ID of the caller. 182.El 183.Sh LEGACY SYNOPSIS 184.Fd #include <sys/types.h> 185.Fd #include <sys/resource.h> 186.Pp 187The include file 188.In sys/types.h 189is necessary. 190.Pp 191.Ft int 192.br 193.Fo getpriority 194.Fa "int which" 195.Fa "int who" 196.Fc ; 197.Pp 198.Ft int 199.br 200.Fo setpriority 201.Fa "int which" 202.Fa "int who" 203.Fa "int value" 204.Fc ; 205.Pp 206The type of 207.Fa who 208has changed. 209.Sh SEE ALSO 210.Xr nice 1 , 211.Xr fork 2 , 212.Xr setiopolicy_np 3 , 213.Xr compat 5 , 214.Xr renice 8 215.Sh HISTORY 216The 217.Fn getpriority 218function call appeared in 219.Bx 4.2 . 220