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 July 23, 1994 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.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.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.Ar -pid 59.Sh DESCRIPTION 60.Nm Rtprio 61is used for controlling realtime process scheduling. 62.Pp 63.Nm Idprio 64is used for controlling idletime process scheduling, and can be called 65with the same options as 66.Nm rtprio . 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 76.Nm Rtprio 77or 78.Nm idprio 79when called without arguments will return the realtime priority 80of the current process. 81.Pp 82If 83.Nm 84is called with 1 argument, it will return the realtime priority 85of the process with the specified 86.Ar pid . 87.Pp 88If 89.Ar priority 90is specified, the process or program is run at that realtime priority. 91If 92.Fl t 93is specified, the process or program is run as a normal (non-realtime) 94process. 95.Pp 96If 97.Ar -pid 98is specified, the process with the process identifier 99.Ar pid 100will be modified, else if 101.Ar command 102is specified, that program is run with its arguments. 103.Pp 104.Ar Priority 105is an integer between 0 and RTP_PRIO_MAX (usually 31). 0 is the 106highest priority 107.Pp 108.Ar Pid 109of 0 means "the current process". 110.Pp 111Only root is allowed to set realtime or idle priority for a process. 112.Sh DIAGNOSTICS 113If 114.Nm 115execute a command, the exit value is that of the command executed. 116In all other cases, 117.Nm 118exits 0 on success, and 1 for all other errors. 119.Sh EXAMPLES 120To see which realtime priority the current process is at: 121.Bd -literal -offset indent -compact 122.Sy "rtprio" 123.Ed 124.Pp 125To see which realtime priority of process 126.Em 1423 : 127.Bd -literal -offset indent -compact 128.Sy "rtprio 1423" 129.Ed 130.Pp 131To run 132.Xr cron 8 133at the lowest realtime priority: 134.Bd -literal -offset indent -compact 135.Sy "rtprio 31 cron" 136.Ed 137.Pp 138To change the realtime priority of process 139.Em 1423 140to 141.Em 16 : 142.Bd -literal -offset indent -compact 143.Sy "rtprio 16 -1423" 144.Ed 145.Pp 146To run 147.Xr tcpdump 1 148without realtime priority: 149.Bd -literal -offset indent -compact 150.Sy "rtprio -t tcpdump" 151.Ed 152.Pp 153To change the realtime priority of process 154.Em 1423 155to 156.Dv RTP_PRIO_NORMAL 157(non-realtime/normal priority): 158.Bd -literal -offset indent -compact 159.Sy "rtprio -t -1423" 160.Ed 161.Pp 162To make depend while not disturbing other machine usage: 163.Bd -literal -offset indent -compact 164.Sy "idprio 31 make depend" 165.Ed 166.Sh SEE ALSO 167.Xr nice 1 , 168.Xr ps 1 , 169.Xr rtprio 2 , 170.Xr setpriority 2 , 171.Xr nice 3 , 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 CAVEATS 180You can lock yourself out of the system by placing a cpu-heavy 181process in a realtime priority. 182.Sh BUGS 183There is no way to set/view the realtime priority of process 0 184(swapper) (see 185.Xr ps 1 ) . 186.Pp 187There is in 188.Bx Free 189no way to ensure that a process page is present in memory therefore 190the process may be stopped for pagein (see 191.Xr mprotect 2 , 192.Xr madvise 2 ) . 193.Pp 194Under 195.Bx Free 196system calls are currently never preempted, therefore non-realtime 197processes can starve realtime processes, or idletime processes can 198starve normal priority processes. 199.Sh AUTHORS 200.An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk 201is the original author. 202This 203implementation in 204.Bx Free 205was substantially rewritten by 206.An David Greenman . 207