priocntl(1) priocntl(1)
NAME
priocntl - set scheduling parameters and priorities (priority control)
SYNOPSIS
priocntl -l Format 1
priocntl -d [-i type] [list] Format 2
priocntl -s [-c class] [options ...] [-i type] [list] Format 3
priocntl -e [-c class] [options ...] command [arguments] Format 4
DESCRIPTION
The priocntl command can be used to
- display or set scheduling parameters (i.e. the priorities and time
quantum allotments) of the specified processes.
- display the current configuration information for the system's pro-
cess scheduler. The scheduler is the process that controls the
scheduling parameters for all processes.
- execute a command with specific scheduling parameters.
Processes fall into distinct classes with a separate scheduling policy
applied to each class. The three process classes currently supported
are the real-time class, the time-sharing class and the fixed-priority
class. The characteristics of these classes and the class-specific
options they accept are described in the sections entitled Real-time
class, Time-sharing class, and Fixed-priority class. Provided you have
the appropriate permissions, you can use priocntl to change the class
and other scheduling parameters associated with a running process.
Caution: A runnable real-time process runs before any other process.
For this reason, inappropriate use of real-time processes
can have a dramatic negative impact on system performance.
Format 1: Display information on all classes
priocntl -l
-l Displays all the classes currently configured on the system
together with class-specific information about each class. The
format and meaning of this information is described in the
appropriate section below.
Page 1 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
Format 2: Display class and parameters for processes
priocntl -d [-i type] [list]
-d Displays the class and class-specific scheduling parameters for
the specified processes.
-i type
The -i option and its associated type argument, together with the
list arguments (if any), specify one or more processes to which
the priocntl command is to apply. How list is interpreted depends
on the type specified. Valid type values and the corresponding
interpretations of list are as follows:
-i pid list is a list of process IDs. The priocntl command
applies to all processes whose process IDs are in the
list.
-i ppid list is a list of parent process IDs. The priocntl com-
mand applies to all processes whose parent process IDs
are in the list.
-i pgid list is a list of process group IDs. The priocntl com-
mand applies to all processes that belong to a process
group in the list.
-i sid list is a list of session IDs. The priocntl command
applies to all processes that belong to one of the ses-
sions in the list.
-i class list is the name of a single class, which you may
specify as RT for real-time, TS for time-sharing, or FP
for fixed-priority. The priocntl command applies to all
processes in the specified class.
-i uid list is a list of user IDs. The priocntl command
applies to all processes whose effective user IDs are
in the list.
-i gid list is a list of group IDs. The priocntl command
applies to all processes whose effective group IDs are
in the list.
-i all The priocntl command applies to all existing processes.
list is ignored in this case. However, the list of
processes may be restricted if you do not have the
required permissions.
-i type not specified:
pid is used as the default identification type.
Page 2 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
list list specifies the processes to which the priocntl command is to
apply. The meanings of the elements in the list are described
under the -i option. If a list is specified, it must be at the
end of the command line. The individual elements of the list must
be separated by blanks or tabs.
list not specified:
If a type argument of pid, ppid, pgid, sid, class, uid, or gid is
specified with the -i option, the process ID, parent process ID,
process group ID, session ID, class, user ID, or group ID respec-
tively of the priocntl command itself is used.
Format 3: Set class and parameters for processes
priocntl -s [-c class] [options ...] [-i type] [list]
-s Sets the class and class-specific parameters of the specified
processes to the values given on the command line.
-c class
class specifies the class to be set for scheduling. Valid class
arguments are RT for real-time, TS for time-sharing, and FP for
fixed-priority.
-c class not specified:
type and list must specify a set of processes which are all in
the same class. Otherwise, priocntl will abort with an error mes-
sage.
options
Specifies the class-specific options. Valid options for these
classes are described in the sections entitled Real-time class,
Time-sharing class, and Fixed-priority class.
No options specified:
The class-specific parameters are set to the default values for
the class specified by -c class, or to the default values for the
process's current class if the -c class option has also been
omitted.
-i type
This option specifies the processes whose parameters are to be
set. Possible values are described under Format 2.
list Together with -i type, list specifies the processes whose parame-
ters are to be set. See Format 2 for more details.
Page 3 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
In order to change the scheduling parameters of a specific process
with priocntl, your real or effective user ID must match the real or
effective user ID of this process, unless you have the system
administrator's effective user ID. These are the minimum requirements
enforced for all classes. An individual class may impose additional
restrictions when setting processes to that class or when setting
class-specific parameters.
When -i type and list specify a list of processes, priocntl acts on
these processes in implementation-specific order. If priocntl encoun-
ters an error for one or more of the specified processes, it may or
may not continue through the list of processes, depending on the
nature of the error. If the error is due to insufficient permissions,
priocntl issues an error message and then continues through the rest
of the processes, resetting the parameters for all processes for which
you have the required permissions. If the cause of the error is not
due to permissions, priocntl terminates immediately without acting on
the other processes in the list and issues an error message.
A special sys scheduling class exists for scheduling the execution of
certain system processes (such as the swapper process, which swaps
data in and out of disk storage). It is not possible to change the
class of any process to sys. In addition, any processes in the sys
class are ignored if they are specified with -i type and list.
Example:
If type were uid, a list consisting of a zero would specify all
processes with a user ID of zero except processes in the sys
class and (if changing the parameters using the -s option) the
init process.
The init process (process ID 1) is a special case. If you want
priocntl to change the class or other scheduling parameters of the
init process, you must specify pid for type and 1 for list. You may
assign the init process to any class configured on the system, but the
time-sharing class is almost always the appropriate choice. Other
classes may have negative effects.
Format 4: Execute a command with specific parameters
priocntl -e [-c class] [option ...] command [arguments]
-e Executes command with the class and scheduling options specified.
-c class
class specifies the class to be set for the command to be exe-
cuted. Valid class arguments are RT for real-time, TS for time-
sharing, and FP for fixed-priority.
-c class not specified:
The command is executed in the user's current class.
Page 4 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
option
Specifies the class-specific options. Valid options for both
classes are described in the sections entitled Real-time class,
Time-sharing class, and Fixed-priority class.
No options specified:
The command is executed with the default values for the class
specified by -c class, or with the default values for the user's
current class if the -c class option has also been omitted.
command
The command to be executed with the specified parameters in the
specified class.
arguments
Arguments for the command to be executed.
Real-time class
The real-time class provides fixed-priority preemptive CPU scheduling
for those processes requiring fast and deterministic response and
absolute user control of scheduling priorities. If the real-time class
is configured on the system it should have exclusive control of the
highest range of scheduling priorities on the system. This ensures
that a runnable real-time process is given CPU service before any
other process.
A real-time priority (rtpri) may be assigned to a process in the
real-time class. Real-time priorities range from 0 to x, where the
value of x is configurable and can be displayed for a specific confi-
guration by means of the priocntl -l command.
Real-time scheduling is fixed-priority scheduling. The priority of a
real-time process never changes unless the user or an appropriate pro-
gram changes it explicitly.
For processes in the real-time class, the rtpri value is, for all
practical purposes, equivalent to the scheduling priority of the pro-
cess. The rtpri value determines the scheduling priority of a real-
time process relative to other processes within its class. A higher
rtpri value represents a higher priority. Since the real-time class
controls the highest range of CPU scheduling priorities in the system,
it is guaranteed that a runnable process with the highest rtpri value
is always assigned CPU time before any other process in the system.
In addition to using priocntl to control priorities, you can also use
it to influence the length of the time quantum allotted to a process
in the real-time class. The time quantum value specifies the maximum
amount of CPU time a process is assigned, provided that it does not
enter an external event wait state (sleep) such as during hard disk
access. If another process becomes runnable with a higher priority,
Page 5 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
the currently running process may be preempted before receiving its
full time quantum.
The command
priocntl -d[ -i type] [list]
can be used to display the priority and time quantum (in milliseconds)
for each process in the real-time class.
Valid options for setting real-time parameters (-s and -e) are:
-p rtpri
Sets the real-time priority of the specified process(es) to
rtpri.
Option -p not specified:
If the process is already in the real-time class, the priority
remains unchanged. If the class of a process is changed to real-
time from some other class, the priority defaults to a value of
0.
-t tqntm
Sets the time quantum for the specified process(es) to tqntm. If
0 is specified or a value greater than the maximum permitted,
priocntl aborts with an error message. The maximum value depends
on the implementation.
Option -t not specified:
If the process is already in the real-time class, the time quan-
tum remains unchanged. If the class of a process is changed to
real-time from some other class, the time quantum defaults to a
value dependent on the priority and system configuration [see
rtdptbl(4)].
-r resolution
resolution defines the units in which the time quantum is speci-
fied with the -t option. resolution is a positive integer between
1 and 1,000,000,000 inclusive. The resolution used is the
reciprocal of resolution in seconds.
Example:
-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 high (nanosecond) resolution may be specified, the
specified time quantum length is always rounded up by the system
to the next integral multiple of the system clock's resolution.
Page 6 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
Example:
The highest resolution currently available on a system is 10
milliseconds. If the -t and -r options are used to specify a
time quantum of 34 milliseconds, it will be rounded up to 40
milliseconds on that system.
The -r option can only be specified together with the -t option.
Option -r not specified:
1 millisecond resolution is assumed for the time quantum set with
-t.
Any combination of the -p and -t options (and possibly -r) may be used
together with -s or -e.
Only the system administrator may change the class of a process from
any other class to real-time. To change the priority or the time quan-
tum of a real-time process, you must either have system administrator
privileges, or you must currently be in the real-time class (i.e. your
command interpreter must be running as a real-time process) and have
the same real or effective user ID as the process whose parameters are
to be changed.
The real-time priority and time quantum are inherited across the
fork(2) and exec(2) system calls.
Time-sharing class
The time-sharing scheduling policy provides for a fair and effective
allocation of CPU time among processes with varying CPU consumption
characteristics. The objectives of the time-sharing policy are to pro-
vide good response time to interactive processes and good throughput
to CPU-bound jobs while providing a degree of user control over
scheduling.
A time-sharing user priority (tsupri) may be assigned to a process in
the time-sharing class. Time-sharing priorities range from -x to +x,
where the value of x is configurable and can be displayed by for a
specific configuration by means of the priocntl -l command.
The purpose of the time-sharing priority is to provide some degree of
user 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.
Page 7 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
In addition to the system-wide limits on user priority (displayed with
priocntl -l), there is a per-process user priority limit (time-sharing
user priority limit, tsuprilim).
The command
priocntl -d [-i type] [list]
can be used to display the user priority and user priority limit for
each specified time-sharing process.
Valid options for setting time-sharing parameters (-s and -e) are:
-m tsuprilim
May only be set in conjunction with -e or -s. Sets the user
priority limit of the specified process(es) to tsuprilim.
Any time-sharing process may lower its own user priority limit or
that of another process with the same user ID, but only a time-
sharing process with system administrator privileges may raise
the limit. When changing the class of a process to time-sharing
from some other class, system administrator privileges are
required in order to set a limit to a value greater than zero.
Option -m not specified:
If the process is already in the time-sharing class, the user
priority limit remains unchanged. If the class of a process is
changed to time-sharing from some other class, the limit defaults
to a value of 0.
-p tsupri
May only be set in conjunction with -e or -s. Sets the user
priority of the specified process(es) to tsupri.
Any time-sharing process may set its own user priority or that of
another process with the same user ID to any value less than or
equal to the process's priority limit. Attempts to set the tsupri
above the tsuprilim or set the tsuprilim below the tsupri result
in the tsupri being set equal to the tsuprilim.
Option -p not specified:
If the process is already in the time-sharing class, the user
priority normally remains unchanged. If the class of a process is
changed to time-sharing from some other class, the user priority
defaults to the value of the user priority limit set.
Page 8 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
Exception:
If the -p option is not specified and -m is used to set a
tsuprilim below the current tsupri, the tsupri is changed to the
tsuprilim which is being set.
Any combination of the -m and -p options may be used with -s or -e.
The user priority and user priority limit are inherited across the
fork(2) and exec(2) system calls.
Fixed-priority class
The fixed-priority class provides a fixed-priority preemptive schedul-
ing policy for those processes requiring fast and deterministic
response and absolute user/application control of scheduling priori-
ties.
The fixed-priority class has a range of fixed-priority priority
(fppri) values that may be assigned to processes within the class.
Fixed-priority priorities range from 0 to x, where the value of x is
configurable and can be displayed for a specific installation by using
the command priocntl -l.
As the name implies, the fixed-priority scheduling policy is a fixed-
priority policy. The scheduling priority of a fixed-priority process
never changes except as the result of an explicit request by the
user/application to change the fppri value of the process.
For processes in the fixed-priority class, the fppri value is, for all
practical purposes, equivalent to the scheduling priority of the pro-
cess. The fppri value completely determines the scheduling priority of
a fixed-priority process relative to other processes within its class.
Numerically higher fppri values represent higher priorities.
In addition to providing control over priority, priocntl provides for
control over the length of the time quantum allotted to processes in
the fixed-priority 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 type] [list]
displays the fixed-priority priority and time quantum (in millisecond
resolution) for each fixed-priority process in the set specified by
type and list.
Page 9 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
The valid class-specific options for setting fixed-priority parameters
are:
-p fppri
Set the fixed-priority priority of the specified process(es) to
fppri.
-t tqntm [-r resolution]
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 fixed-priority class. If an option is omitted
and the process is currently fixed-priority the associated parameter
is unaffected. If an option is omitted when changing the class of a
process to fixed-priority from some other class, the associated param-
eter 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 fppri and on
the system configuration [see fpdptbl(4)].
When using the -t tqntm option you may optionally specify a resolution
using the -r resolution option. (If no resolution is specified, mil-
lisecond resolution is assumed.) If resolution is specified it must be
a positive integer between 1 and 1,000,000,000 inclusive and the reso-
lution used is the reciprocal of resolution 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 system
to the next integral multiple of the system clock's resolution.
Requests for time quantums of zero or quantums greater than the (typi-
cally very large) implementation-specific maximum quantum result in an
error.
In order to set the time quantum to an infinite value, enter the
INFINITE string instead of a value for duration. If duration is set to
the DEFAULT value, the time quantum value of the parameter table of
the fixed-priority scheduler is used [see fpdptbl(4)].
In order to change the class of a process to fixed-priority (from any
other class) the user invoking priocntl must have super-user privi-
lege. In order to change the fppri value or time quantum of a fixed-
priority process the user invoking priocntl must either be super-user,
or must currently be in the fixed-priority class (shell running as a
fixed-priority process) with a real or effective user ID matching the
real or effective user ID of the target process.
The fixed-priority priority and time quantum are inherited across the
fork(2) and exec(2) system calls.
Page 10 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
PROCESSOR AFFINITY AND BINDING CONSIDERATIONS
In order to increase the cache hit rates of a multiprocessor, a pro-
cess should generally execute on a particular processor. This affinity
for a particular processor will reduce the required memory bandwidth
for the process (and for the system as a whole). If a process has not
run "recently" then it probably only has a small cache state in any
given processor - and thus should loose its affinity for any particu-
lar processor.
This affinity mechanism can be enabled or disabled on a per-process
basis by the super user [see mpcntl(3X)]. The affinity mechanism
defaults to on for the TS and FP classes and to off for the RT class.
A process can also be bound to a set of processors. If a processor has
been so bound, then it will only run on one of the processors of that
set. If there is a idle processor that is not in the processes binding
set - then the process will still wait until there is a processor in
its set that is not running a higher priority process.
Process bindings can be established by the process [see mpcntl(3X)],
or can be temporarily established by the kernel (if the kernel is exe-
cuting driver code that must run on a particular CPU).
ERROR MESSAGES
Process(es) not found
None of the specified processes exists.
Specified processes from different classes
The -s option was specified to set parameters; the -c class
option was not specified; and the specified processes are from
different classes.
Invalid option or argument
An option or option argument cannot be recognized or is invalid.
Permissions error encountered on pid x
You do not have the appropriate permissions to change the set-
tings for the process with process ID x.
EXAMPLES
Example 1
The following command sets the class of any non-real-time processes
identified by the specified process IDs to real-time and sets their
real-time priority to the default value of 0. The real-time priorities
of processes already in the real-time class remain unchanged. The time
quantums of all of the specified processes are set to 1/10 seconds (1
unit with a resolution of 1/10 seconds).
$ priocntl -s -c RT -t 1 -r 10 -i pid 1234 2345 3456
Page 11 Reliant UNIX 5.44 Printed 11/98
priocntl(1) priocntl(1)
Example 2
The next command executes the specified command in the real-time class
with a real-time priority of 15 and a time quantum of 20 milliseconds.
$ priocntl -e -c RT -p 15 -t 20 command
Example 3
The following command sets the class of all processes with UID 17 to
time-sharing, assuming they are not already in that class. The user
priority limit and the user priority are set to the default value 0.
The time-sharing parameters of processes already in the time-sharing
class remain unchanged:
$ priocntl -s -c TS -i uid 17
Example 4
In this example, the specified command is executed in the time-sharing
class with a user priority limit of 0 and a user priority of -15:
$ priocntl -e -c TS -m 0 -p -15 command arguments
Example 5
priocntl sets the class of any non-fixed-priority processes selected
by type and list to fixed-priority and sets their fixed-priority
priority to the default value of 0. The real-time priorities 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 -s -c FP -t 1 -r 10 -i type list
Example 6
priocntl executes command in the fixed-priority class with a fixed-
priority priority of 15 and a time quantum of 20 milliseconds:
priocntl -e -c FP -p 15 -t 20 command
SEE ALSO
nice(1), ps(1), priocntl(2), fpdptbl(4), rtdptbl(4), tsdptbl(4).
Page 12 Reliant UNIX 5.44 Printed 11/98