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.