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