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