Sweep-fix man page section order to match mdoc(7), part 5/5.
[dragonfly.git] / usr.sbin / rtprio / rtprio.1
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
41 or 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
61 The
62 .Nm
63 utility is used for controlling realtime process scheduling.
64 .Pp
65 The
66 .Nm idprio
67 utility is used for controlling idletime process scheduling, and can be called
68 with the same options as
69 .Nm .
70 .Pp
71 A process with a realtime priority is not subject to priority
72 degradation, and will only be preempted by another process of equal or
73 higher realtime priority.
74 .Pp
75 A process with an idle priority will run only when no other
76 process is runnable and then only if its idle priority is equal or
77 greater than all other runnable idle priority processes.
78 .Pp
79 Both
80 .Nm
81 or
82 .Nm idprio
83 when called without arguments will return the realtime priority
84 of the current process.
85 .Pp
86 If
87 .Nm
88 is called with 1 argument, it will return the realtime priority
89 of the process with the specified
90 .Ar pid .
91 .Pp
92 If
93 .Ar priority
94 is specified, the process or program is run at that realtime priority.
95 If
96 .Fl t
97 is specified, the process or program is run as a normal (non-realtime)
98 process.
99 .Pp
100 If
101 .Ar -pid
102 is specified, the process with the process identifier
103 .Ar pid
104 will be modified, else if
105 .Ar command
106 is specified, that program is run with its arguments.
107 .Pp
108 .Ar Priority
109 is an integer between 0 and RTP_PRIO_MAX (usually 31). 0 is the
110 highest priority
111 .Pp
112 .Ar Pid
113 of 0 means "the current process".
114 .Pp
115 Only root is allowed to set realtime or idle priority for a process.
116 .Sh EXAMPLES
117 To see which realtime priority the current process is at:
118 .Bd -literal -offset indent -compact
119 .Sy "rtprio"
120 .Ed
121 .Pp
122 To see which realtime priority of process
123 .Em 1423 :
124 .Bd -literal -offset indent -compact
125 .Sy "rtprio 1423"
126 .Ed
127 .Pp
128 To run
129 .Xr cron 8
130 at the lowest realtime priority:
131 .Bd -literal -offset indent -compact
132 .Sy "rtprio 31 cron"
133 .Ed
134 .Pp
135 To change the realtime priority of process
136 .Em 1423
137 to
138 .Em 16 :
139 .Bd -literal -offset indent -compact
140 .Sy "rtprio 16 -1423"
141 .Ed
142 .Pp
143 To run
144 .Xr tcpdump 1
145 without realtime priority:
146 .Bd -literal -offset indent -compact
147 .Sy "rtprio -t tcpdump"
148 .Ed
149 .Pp
150 To change the realtime priority of process
151 .Em 1423
152 to
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
159 To 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
164 If
165 .Nm
166 execute a command, the exit value is that of the command executed.
167 In all other cases,
168 .Nm
169 exits 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
178 The
179 .Nm
180 utility appeared in
181 .Fx 2.0 ,
182 but is similar to the HP-UX version.
183 .Sh AUTHORS
184 .An -nosplit
185 .An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk
186 is the original author.
187 This
188 implementation was substantially rewritten by
189 .An David Greenman .
190 .Sh CAVEATS
191 You can lock yourself out of the system by placing a cpu-heavy
192 process in a realtime priority.
193 .Sh BUGS
194 There is no way to set/view the realtime priority of process 0
195 (swapper) (see
196 .Xr ps 1 ) .
197 .Pp
198 There is in
199 .Dx
200 no way to ensure that a process page is present in memory therefore
201 the process may be stopped for pagein (see
202 .Xr mprotect 2 ,
203 .Xr madvise 2 ) .
204 .Pp
205 Under
206 .Dx
207 system calls are currently never preempted, therefore non-realtime
208 processes can starve realtime processes, or idletime processes can
209 starve normal priority processes.