add more concrete examples of how to use chrt(1)

I've come looking at this manpage with the simple "how do I make this
process use realtime scheduling?" question and couldn't find a
definite answer. Of course, RT is more complicated than "just make
this real time": there's various queues and scheduling classes, but I
think it's worth giving a good, simple example that should basically
work.

In particular, my use case was "my audio is stuttering, is this a
scheduling problem?" By picking the RR scheduler, we set a realtime
scheduling priority that's lower than kernel threads (e.g. migration
is FF/99, irq is FF/50) so that we go above existing processes, but
without kicking out more critical systems.

This, of course, is a matter of taste, and the settings here are a
little arbitrary. I send this patch in the hope that either those are
accepted as canon (which would surprise me) or that someone comes up
with a more canonical example.

The "reset" example also seems like a more critical addition to the
manual.

Finally, I change the name of the section from USAGE to the more
standard EXAMPLES, as per man-pages(7).

diff --git a/schedutils/chrt.1.adoc b/schedutils/chrt.1.adoc
index 6ccba7dfb0c56a45e9f55fae38eb54604d5f2561..90cb7496fa1bc6b69b4ecc34016cd3ad01701262 100644 (file)
--- a/schedutils/chrt.1.adoc
+++ b/schedutils/chrt.1.adoc
@@ -103,7 +103,7 @@ Show status information.
 
 include::man-common/help-version.adoc[]
 
-== USAGE
+== EXAMPLES
 
 //TRANSLATORS: Keep {colon} untranslated
 The default behavior is to run a new command{colon}::
@@ -120,6 +120,18 @@ Or set them{colon}::
 
 *chrt -r -p* _priority PID_
 
+This, for example, sets real-time scheduling to priority _30_ for the
+process _PID_ with the *SCHED_RR* (round-robin) class:
+
+*chrt -r -p 30 _PID_*
+
+Reset priorities to default for a process:
+
+*chrt -o -p 0 _PID_*
+
+See *sched*(7) for a detailed discussion of the different scheduler
+classes and how they interact.
+
 == PERMISSIONS
 
 A user must possess *CAP_SYS_NICE* to change the scheduling attributes of a process. Any user can retrieve the scheduling information.