1.\" 2.\" Copyright (c) 1994, Henrik Vestergaard Draboel 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by Henrik Vestergaard Draboel. 16.\" 4. The name of the author may not be used to endorse or promote products 17.\" derived from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.Dd December 8, 2021 32.Dt RTPRIO 1 33.Os 34.Sh NAME 35.Nm rtprio , 36.Nm idprio 37.Nd execute, examine or modify a utility's or process's realtime 38or idletime scheduling priority 39.Sh SYNOPSIS 40.Nm [id|rt]prio 41.Nm [id|rt]prio 42.Oo Fl Oc Ns Ar pid 43.Nm [id|rt]prio 44.Ar priority 45.Ar command 46.Op args 47.Nm [id|rt]prio 48.Ar priority 49.Fl Ar pid 50.Nm [id|rt]prio 51.Fl t 52.Ar command 53.Op args 54.Nm [id|rt]prio 55.Fl t 56.Fl Ar pid 57.Sh DESCRIPTION 58The 59.Nm 60utility is used for controlling realtime process scheduling. 61.Pp 62The 63.Nm idprio 64utility is used for controlling idletime process scheduling, and can be called 65with the same options as 66.Nm . 67.Pp 68A process with a realtime priority is not subject to priority 69degradation, and will only be preempted by another process of equal or 70higher realtime priority. 71.Pp 72A process with an idle priority will run only when no other 73process is runnable and then only if its idle priority is equal or 74greater than all other runnable idle priority processes. 75.Pp 76Both 77.Nm 78or 79.Nm idprio 80when called without arguments will return the realtime priority 81of the current process. 82.Pp 83If 84.Nm 85is called with 1 argument, it will return the realtime priority 86of the process with the specified 87.Ar pid . 88.Pp 89If 90.Ar priority 91is specified, the process or program is run at that realtime priority. 92If 93.Fl t 94is specified, the process or program is run as a normal (non-realtime) 95process. 96.Pp 97If 98.Ar -pid 99is specified, the process with the process identifier 100.Ar pid 101will be modified, else if 102.Ar command 103is specified, that program is run with its arguments. 104.Pp 105.Ar Priority 106is an integer between 0 and RTP_PRIO_MAX (usually 31). 1070 is the 108highest priority 109.Pp 110.Ar Pid 111of 0 means "the current process". 112.Pp 113Only root is allowed to set realtime or idle priority for a process. 114Exceptional privileges can be granted through the 115.Xr mac_priority 4 116policy and the realtime and idletime user groups. 117The 118.Xr sysctl 8 119variable 120.Va security.bsd.unprivileged_idprio 121is deprecated. 122If set to non-zero, it lets any user modify the idle priority of processes 123they own. 124.Pp 125Note that idle priority increases the chance that a deadlock can occur 126if a process locks a required resource and then does 127not get to run. 128.Sh EXIT STATUS 129If 130.Nm 131execute a command, the exit value is that of the command executed. 132In all other cases, 133.Nm 134exits 0 on success, and 1 for all other errors. 135.Sh EXAMPLES 136To see which realtime priority the current process is at: 137.Dl rtprio 138.Pp 139To see which realtime priority of process 1423: 140.Dl "rtprio 1423" 141.Pp 142To run 143.Xr cron 8 144at the lowest realtime priority: 145.Dl "rtprio 31 cron" 146.Pp 147To change the realtime priority of process 1423 to 16: 148.Dl "rtprio 16 -1423" 149.Pp 150To run 151.Xr tcpdump 1 152without realtime priority: 153.Dl "rtprio -t tcpdump" 154.Pp 155To change the realtime priority of process 1423 156to 157.Dv RTP_PRIO_NORMAL 158(non-realtime/normal priority): 159.Dl "rtprio -t -1423" 160.Pp 161To make depend while not disturbing other machine usage: 162.Dl "idprio 31 make depend" 163.Sh SEE ALSO 164.Xr nice 1 , 165.Xr ps 1 , 166.Xr rtprio 2 , 167.Xr setpriority 2 , 168.Xr nice 3 , 169.Xr mac_priority 4 , 170.Xr renice 8 171.Sh HISTORY 172The 173.Nm 174utility appeared in 175.Fx 2.0 , 176but is similar to the HP-UX version. 177.Sh AUTHORS 178.An -nosplit 179.An Henrik Vestergaard Draboel Aq Mt hvd@terry.ping.dk 180is the original author. 181This 182implementation in 183.Fx 184was substantially rewritten by 185.An David Greenman . 186.Sh CAVEATS 187You can lock yourself out of the system by placing a cpu-heavy 188process in a realtime priority. 189.Sh BUGS 190There is no way to set/view the realtime priority of process 0 191(swapper) (see 192.Xr ps 1 ) . 193.Pp 194There is in 195.Fx 196no way to ensure that a process page is present in memory therefore 197the process may be stopped for pagein (see 198.Xr mprotect 2 , 199.Xr madvise 2 ) . 200.Pp 201Under 202.Fx 203system calls are currently never preempted, therefore non-realtime 204processes can starve realtime processes, or idletime processes can 205starve normal priority processes. 206