From 3b0f093fdcee4798c10c948450193dd2e57c8207 Mon Sep 17 00:00:00 2001
From: dg <dg@FreeBSD.org>
Date: Sun, 2 Oct 1994 04:48:21 +0000
Subject: "idle priority" support. Based on code from Henrik Vestergaard
 Draboel, but substantially rewritten by me.

---
 usr.sbin/rtprio/rtprio.1 | 92 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 62 insertions(+), 30 deletions(-)

(limited to 'usr.sbin/rtprio/rtprio.1')

diff --git a/usr.sbin/rtprio/rtprio.1 b/usr.sbin/rtprio/rtprio.1
index a2cc7dc..5542f12 100644
--- a/usr.sbin/rtprio/rtprio.1
+++ b/usr.sbin/rtprio/rtprio.1
@@ -34,35 +34,50 @@
 .Dt RTPRIO 1
 .Os 
 .Sh NAME
-.Nm rtprio
-.Nd execute, examine or modify a process's realtime scheduling priority
+.Nm rtprio ,
+.Nm idprio
+.Nd execute, examine or modify a utilitys or process realtime 
+or idletime scheduling priority
 .Sh SYNOPSIS
 
-.Nm rtprio
-.Nm rtprio 
+.Nm [id|rt]prio
+.Nm [id|rt]prio 
 .Ar pid
-.Nm rtprio 
+.Nm [id|rt]prio 
 .Ar priority
 .Ar command
 .Op args
-.Nm rtprio 
+.Nm [id|rt]prio 
 .Ar priority
 .Ar -pid
-.Nm rtprio 
+.Nm [id|rt]prio 
 .Ar -t
 .Ar command
 .Op args
-.Nm rtprio 
+.Nm [id|rt]prio 
 .Ar -t
 .Ar -pid
 .Sh DESCRIPTION
 .Nm Rtprio
-is used for controlling realtime process scheduling. A process with a
-realtime priority is not subject to priority degradation, and will only
-be preempted by another process of equal or higher realtime priority.
+is used for controlling realtime process scheduling. 
 
-.Nm Rtprio
-called without arguments, will return the realtime priority
+.Nm Idprio
+is used for controlling idletime process scheduling, and can be called
+with the same options as 
+.Nm Rtprio .
+
+A process with a realtime priority is not subject to priority
+degradation, and will only be preempted by another process of equal or
+higher realtime priority.
+
+A process with an idle priority will run only when no other
+process is runnable and then only if it's idle priority is equal or
+greater than all other runnable idle priority processes.
+
+.Nm Rtprio 
+or
+.Nm Idprio 
+when called without arguments will return the realtime priority
 of the current process.
 
 If
@@ -81,23 +96,27 @@ process.
 
 If
 .Ar -pid
-is specified, the process with that pid will be modified, else
-if 
+is specified, the process with the process identifier "pid" will be
+modified, else if
 .Ar command 
 is specified, that program is run with its arguments.
 
 .Ar Priority
-is an integer between 0 (RTPRIO_MIN) and 31 (RTPRIO_MAX). 0 is the
+is an integer between 0 and RTP_PRIO_MAX (usually 31). 0 is the
 highest priority
 
 .Ar Pid
 of 0 means "the current process".
 
-Only root is allowed to set realtime priorities.
+Only root is allowed to set realtime priorities. Non-root processes may
+set idle priority levels for the current process only.
 .Sh RETURN VALUE
+If
 .Nm rtprio
-returns the (new) realtime priority of the process (see rtprio(2)), or
--1 for all usage errors.
+execute a command, the exit value is that of the command executed.
+In all other cases,
+.Nm
+exits with 0 for success and 1 for all other errors.
 .Sh EXAMPLES
 .\LP
 
@@ -131,16 +150,17 @@ To run \fItcpdump\fP without realtime priority:
 .Ed
 
 .\.LP
-To change the realtime priority of process \fI1423\fP to RTRIO_RTOFF
-(no realtime):
+To change the realtime priority of process \fI1423\fP to RTP_PRIO_NORMAL
+(non-realtime/"normal" priority):
 .Bd -literal -offset indent -compact
 \fBrtprio -t -1423\fP
 .Ed
-.Sh DIAGNOSTICS
-The
-.Nm rtprio
-utility shall exit with value of the (new) realtime priority of the
-program.
+
+.\.LP
+To make depend while not disturbing other machine usage:
+.Bd -literal -offset indent -compact
+\fBidprio 31 make depend\fP
+.Ed
 .Sh SEE ALSO
 .Xr rtprio 2 ,
 .Xr nice 1 ,
@@ -153,13 +173,25 @@ The
 utility appeared in
 FreeBSD 2.0,
 but is similar to the HP-UX version.
+.Sh CAVEATS
+You can lock yourself out of the system by placing a cpu-heavy
+process in a realtime priority.
 .Sh BUGS
-You can lock yourself out of the system by placing a cpu-intensive
-process into realtime priority.
-
 There is no way to set/view the realtime priority of process 0
 (swapper) (see ps(1)).
 
+There is in
+FreeBSD
+no way to ensure that a process page is present in memory therefore
+the process may be stopped for pagein. (See mprotect(2), madvise(2)).
+
+Under
+FreeBSD
+system calls are currently never preempted, therefore non-realtime
+processes can starve realtime procesess, or idletime processes can
+starve normal priority processes.
+
 Others ...
 .Sh AUTHOR
-Henrik Vestergaard Draboel - hvd@terry.ping.dk
+Henrik Vestergaard Draboel - hvd@terry.ping.dk is the original author. This
+implementation in FreeBSD was substantially rewritten by David Greenman.
-- 
cgit v1.1