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