priocntl(1) USER COMMANDS priocntl(1)
NAME
priocntl - process scheduler control
SYNOPSIS
priocntl -l
priocntl -d [-i idtype] [idlist]
priocntl -s [-c class] [class-specific options] [-i idtype]
[idlist]
priocntl -e [-c class] [class-specific options] command
[argument(s)]
DESCRIPTION
The priocntl command displays or sets scheduling parameters
of the specified process(es). It can also be used to
display the current configuration information for the
system's process scheduler or execute a command with speci-
fied scheduling parameters. Processes fall into distinct
classes with a separate scheduling policy applied to each
class. The two process classes currently supported are the
real-time class and the time-sharing class. The charac-
teristics of these two classes and the class-specific
options they accept are described below under the headings
REAL-TIME CLASS and TIME-SHARING CLASS. With appropriate
permissions, the priocntl command can change the class and
other scheduling parameters associated with a running pro-
cess. In the default configuration, a runnable real-time
process runs before any other process. Therefore, inap-
propriate use of real-time processes can have a dramatic
negative impact on system performance. The command
priocntl -l
displays a list of classes currently configured in the sys-
tem along with class-specific information about each class.
The format of the class-specific information displayed is
described under the appropriate heading below. The -d and
-s options to priocntl allow the user to display or set the
scheduling parameters associated with a set of processes.
The -i option and its associated idtype argument, together
with the idlist arguments to priocntl (if any), specify one
or more processes to which the priocntl command is to apply.
The interpretation of idlist depends on the value of idtype.
The valid idtype arguments and corresponding interpretations
of idlist are as follows:
-i pid idlist is a list of process IDs. The priocntl
command applies to the specified processes.
-i ppid idlist is a list of parent process IDs. The
priocntl command applies to all processes whose
parent process ID is in the list.
-i pgid idlist is a list of process group IDs. The
priocntl command applies to all processes in
1
priocntl(1) USER COMMANDS priocntl(1)
the specified process groups.
-i sid idlist is a list of session IDs. The priocntl
command applies to all processes in the speci-
fied sessions.
-i class idlist consists of a single class name (RT for
real-time or TS for time-sharing). The
priocntl command applies to all processes in
the specified class.
-i uid idlist is a list of user IDs. The priocntl
command applies to all processes with an effec-
tive user ID equal to an ID from the list.
-i gid idlist is a list of group IDs. The priocntl
command applies to all processes with an effec-
tive group ID equal to an ID from the list.
-i all The priocntl command applies to all existing
processes. No idlist should be specified (if
one is it is ignored). The permission restric-
tions described below still apply.
If the -i idtype option is omitted when using the -d or -s
options the default idtype of pid is assumed. If an idlist
is present it must appear last on the command line and the
elements of the list must be separated by white space. If
no idlist is present an idtype argument of pid, ppid, pgid,
sid, class, uid, or gid specifies the process ID, parent
process ID, process group ID, session ID, class, user ID, or
group ID respectively of the priocntl command itself. The
command
priocntl -d [-i idtype] [idlist]
displays the class and class-specific scheduling parameters
of the process(es) specified by idtype and idlist. The com-
mand
priocntl -s [-c class] [class-specific options] [-i
idtype] [idlist]
sets the class and class-specific parameters of the speci-
fied processes to the values given on the command line. The
-c class option specifies the class to be set. (The valid
class arguments are RT for real-time or TS for time-
sharing). The class-specific parameters to be set are
specified by the class-specific options as explained under
the appropriate heading below. If the -c class option is
omitted, idtype and idlist must specify a set of processes
which are all in the same class, otherwise an error results.
If no class-specific options are specified the process's
class-specific parameters are set to the default values for
the class specified by -c class (or to the default parameter
values for the process's current class if the -c class
option is also omitted). In order to change the scheduling
2
priocntl(1) USER COMMANDS priocntl(1)
parameters of a process using priocntl the real or effective
user ID of the user invoking priocntl must match the real or
effective user ID of the receiving process or the effective
user ID of the user must be super-user. These are the
minimum permission requirements enforced for all classes.
An individual class may impose additional permissions
requirements when setting processes to that class or when
setting class-specific scheduling parameters. When idtype
and idlist specify a set of processes, priocntl acts on the
processes in the set in an implementation-specific order.
If priocntl encounters an error for one or more of the tar-
get processes, it may or may not continue through the set of
processes, depending on the nature of the error. If the
error is related to permissions, priocntl prints an error
message and then continue through the process set, resetting
the parameters for all target processes for which the user
has appropriate permissions. If priocntl encounters an
error other than permissions, it does not continue through
the process set but prints an error message and exits
immediately. A special sys scheduling class exists for the
purpose of scheduling the execution of certain special sys-
tem processes (such as the swapper process). It is not pos-
sible to change the class of any process to sys. In addi-
tion, any processes in the sys class that are included in
the set of processes specified by idtype and idlist are
disregarded by priocntl. For example, if idtype were uid,
an idlist consisting of a zero would specify all processes
with a UID of zero except processes in the sys class and (if
changing the parameters using the -s option) the init pro-
cess. The init process (process ID 1) is a special case.
In order for the priocntl command to change the class or
other scheduling parameters of the init process, idtype must
be pid and idlist must be consist of only a 1. The init
process may be assigned to any class configured on the sys-
tem, but the time-sharing class is almost always the
appropriate choice. (Other choices may be highly undesir-
able; see the System Administrator's Guide for more informa-
tion.) The command
priocntl -e [-c class] [class-specific options] command
[argument(s)]
executes the specified command with the class and scheduling
parameters specified on the command line (arguments are the
arguments to the command). If the -c class option is omit-
ted the command is run in the user's current class.
REAL-TIME CLASS
The real-time class provides a fixed priority preemptive
scheduling policy for those processes requiring fast and
deterministic response and absolute user/application control
of scheduling priorities. If the real-time class is config-
ured in the system it should have exclusive control of the
highest range of scheduling priorities on the system. This
3
priocntl(1) USER COMMANDS priocntl(1)
ensures that a runnable real-time process is given CPU ser-
vice before any process belonging to any other class. The
real-time class has a range of real-time priority (rtpri)
values that may be assigned to processes within the class.
Real-time priorities range from 0 to x, where the value of x
is configurable and can be displayed for a specific instal-
lation by using the command
priocntl -l
The real-time scheduling policy is a fixed priority policy.
The scheduling priority of a real-time process never changes
except as the result of an explicit request by the
user/application to change the rtpri value of the process.
For processes in the real-time class, the rtpri value is,
for all practical purposes, equivalent to the scheduling
priority of the process. The rtpri value completely deter-
mines the scheduling priority of a real-time process rela-
tive to other processes within its class. Numerically
higher rtpri values represent higher priorities. Since the
real-time class controls the highest range of scheduling
priorities in the system it is guaranteed that the runnable
real-time process with the highest rtpri value is always
selected to run before any other process in the system. In
addition to providing control over priority, priocntl pro-
vides for control over the length of the time quantum allot-
ted to processes in the real-time class. The time quantum
value specifies the maximum amount of time a process may run
assuming that it does not complete or enter a resource or
event wait state (sleep). Note that if another process
becomes runnable at a higher priority the currently running
process may be preempted before receiving its full time
quantum. The command
priocntl -d [-i idtype] [idlist]
displays the real-time priority and time quantum (in mil-
lisecond resolution) for each real-time process in the set
specified by idtype and idlist. The valid class-specific
options for setting real-time parameters are:
-p rtpri Set the real-time priority of the specified
process(es) to rtpri.
-t tqntm [-r res]
Set the time quantum of the specified
process(es) to tqntm. You may optionally
specify a resolution as explained below.
Any combination of the -p and -t options may be used with
priocntl -s or priocntl -e for the real-time class. If an
option is omitted and the process is currently real-time the
associated parameter is unaffected. If an option is omitted
when changing the class of a process to real-time from some
other class, the associated parameter is set to a default
value. The default value for rtpri is 0 and the default for
time quantum is dependent on the value of rtpri and on the
4
priocntl(1) USER COMMANDS priocntl(1)
system configuration; see rtdptbl(4). When using the -t
tqntm option you may optionally specify a resolution using
the -r res option. (If no resolution is specified, mil-
lisecond resolution is assumed.) If res is specified it
must be a positive integer between 1 and 1,000,000,000
inclusive and the resolution used is the reciprocal of res
in seconds. For example, specifying -t 10 -r 100 would set
the resolution to hundredths of a second and the resulting
time quantum length would be 10/100 seconds (one tenth of a
second). Although very fine (nanosecond) resolution may be
specified, the time quantum length is rounded up by the sys-
tem to the next integral multiple of the system clock's
resolution. For example the finest resolution currently
available on the 3B2 is 10 milliseconds (1 ``tick''). If
the -t and -r options are used to specify a time quantum of
34 milliseconds, it is rounded up to 4 ticks (40 mil-
liseconds) on the 3B2. Requests for time quantums of zero
or quantums greater than the (typically very large)
implementation-specific maximum quantum result in an error.
In order to change the class of a process to real-time (from
any other class) the user invoking priocntl must have
super-user privileges. In order to change the rtpri value
or time quantum of a real-time process the user invoking
priocntl must either be super-user, or must currently be in
the real-time class (shell running as a real-time process)
with a real or effective user ID matching the real or effec-
tive user ID of the target process. The real-time priority
and time quantum are inherited across the fork(2) and
exec(2) system calls.
Examples
priocntl -s -c RT -t 1 -r 10 -i idtype idlist
sets the class of any non-real-time processes selected by
idtype and idlist to real-time and sets their real-time
priority to the default value of 0. The real-time priori-
ties of any processes currently in the real-time class are
unaffected. The time quantums of all of the specified
processes are set to 1/10 seconds.
priocntl -e -c RT -p 15 -t 20 command
executes command in the real-time class with a real-time
priority of 15 and a time quantum of 20 milliseconds.
TIME-SHARING CLASS
The time-sharing scheduling policy provides for a fair and
effective allocation of the CPU resource among processes
with varying CPU consumption characteristics. The objec-
tives of the time-sharing policy are to provide good
response time to interactive processes and good throughput
to CPU-bound jobs while providing a degree of
user/application control over scheduling. The time-sharing
class has a range of time-sharing user priority (tsupri)
values that may be assigned to processes within the class.
5
priocntl(1) USER COMMANDS priocntl(1)
User priorities range from -x to +x, where the value of x is
configurable. The range for a specific installation can be
displayed by using the command
priocntl -l
The purpose of the user priority is to provide some degree
of user/application control over the scheduling of processes
in the time-sharing class. Raising or lowering the tsupri
value of a process in the time-sharing class raises or
lowers the scheduling priority of the process. It is not
guaranteed, however, that a time-sharing process with a
higher tsupri value will run before one with a lower tsupri
value. This is because the tsupri value is just one factor
used to determine the scheduling priority of a time-sharing
process. The system may dynamically adjust the internal
scheduling priority of a time-sharing process based on other
factors such as recent CPU usage. In addition to the
system-wide limits on user priority (displayed with priocntl
-l), there is a per process user priority limit (tsuprilim),
which specifies the maximum tsupri value that may be set for
a given process. The command
priocntl -d [-i idtype] [idlist]
displays the user priority and user priority limit for each
time-sharing process in the set specified by idtype and
idlist. The valid class-specific options for setting time-
sharing parameters are:
-m tsuprilim
Set the user priority limit of the specified
process(es) to tsuprilim.
-p tsupri Set the user priority of the specified
process(es) to tsupri.
Any time-sharing process may lower its own tsuprilim (or
that of another process with the same user ID). Only a
time-sharing process with super-user privileges may raise a
tsuprilim. When changing the class of a process to time-
sharing from some other class, super-user privileges are
required in order to set the initial tsuprilim to a value
greater than zero. Any time-sharing process may set its own
tsupri (or that of another process with the same user ID) to
any value less than or equal to the process's tsuprilim.
Attempts to set the tsupri above the tsuprilim (and/or set
the tsuprilim below the tsupri) result in the tsupri being
set equal to the tsuprilim. Any combination of the -l and
-p options may be used with priocntl -s or priocntl -e for
the time-sharing class. If an option is omitted and the
process is currently time-sharing the associated parameter
is normally unaffected. The exception is when the -p option
is omitted and -l is used to set a tsuprilim below the
current tsupri. In this case the tsupri is set equal to the
tsuprilim which is being set. If an option is omitted when
changing the class of a process to time-sharing from some
6
priocntl(1) USER COMMANDS priocntl(1)
other class, the associated parameter is set to a default
value. The default value for tsuprilim is 0 and the default
for tsupri is to set it equal to the tsuprilim value which
is being set. The time-sharing user priority and user
priority limit are inherited across the fork(2) and exec(2)
system calls.
Examples
priocntl -s -c TS -i idtype idlist
sets the class of any non-time-sharing processes selected by
idtype and idlist to time-sharing and sets both their user
priority limit and user priority to 0. Processes already in
the time-sharing class are unaffected.
priocntl -e -c TS -l 0 -p -15 command [arguments]
executes command with the arguments arguments in the time-
sharing class with a user priority limit of 0 and a user
priority of -15.
SEE ALSO
ps(1), nice(1), priocntl(2), rt_dptbl(4).
DIAGNOSTICS
priocntl prints the following error messages: Process(es)
not found: None of the specified processes exists. Speci-
fied processes from different classes: The -s option is
being used to set parameters, the -c class option is not
present, and processes from more than one class are speci-
fied. Invalid option or argument: An unrecognized or
invalid option or option argument is used.
7