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