User Commands priocntl(1)
NAME
priocntl - display or set scheduling parameters of specified
process(es)
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 pro-
cess scheduler or execute a command with specified schedul-
ing parameters.
Processes fall into distinct classes with a separate
scheduling policy applied to each class. The process classes
currently supported are the real-time class, time-sharing
class, interactive class, fair-share class, and the fixed
priority class. The characteristics of these classes and the
class-specific options they accept are described below in
the USAGE section under the headings Real-Time Class, Time-
Sharing Class, Inter-Active Class, Fair-Share Class, and
Fixed-Priority Class. With appropriate permissions, the
priocntl command can change the class and other scheduling
parameters associated with a running process.
In the default configuration, a runnable real-time process
runs before any other process. Therefore, inappropriate use
of real-time processes can have a dramatic negative impact
on system performance.
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, taskid, class, uid, gid, projid, or zoneid
specifies the process ID, parent process ID, process group
ID, session ID, task ID, class, user ID, group ID, project
SunOS 5.11 Last change: 1 Apr 2008 1
User Commands priocntl(1)
ID, or zone 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 command
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, TS for time-sharing,
IA for inter-active, FS for fair-share, or FX for fixed-
priority.)
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 parame-
ters 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 omit-
ted).
In order to change the scheduling parameters of a process
using priocntl the real or effective user ID (respectively,
groupID) of the user invoking priocntl must match the real
or effective user ID (respectively, groupID) of the receiv-
ing 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 can impose
additional permissions requirements when setting processes
to that class or when setting class-specific scheduling
SunOS 5.11 Last change: 1 Apr 2008 2
User Commands priocntl(1)
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 target processes, it can or cannot 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 continues 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 system processes
(such as the swapper process). It is not possible to change
the class of any process to sys. In addition, 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 0, 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. 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
can be assigned to any class configured on the system, but
the time-sharing class is almost always the appropriate
choice. Other choices can be highly undesirable; see the
System Administration Guide: Basic Administration for more
information.
The command
priocntl -e [-c class] [class-specific options] command \
[argument...]
SunOS 5.11 Last change: 1 Apr 2008 3
User Commands priocntl(1)
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 omitted
the command is run in the user's current class.
OPTIONS
The following options are supported:
-c class Specifies the class to be set. (The valid class
arguments are RT for real-time, TS for time-
sharing, IA for inter-active, FS for fair-
share, or FX for fixed-priority.) If the speci-
fied class is not already configured, it is
automatically configured.
-d Displays the scheduling parameters associated
with a set of processes.
-e Executes a specified command with the class and
scheduling parameters associated with a set of
processes.
-i idtype This option, together with the idlist arguments
(if any), specifies one or more processes to
which the priocntl command is to apply. The
interpretation of idlist depends on the value
of idtype. If the -i idtype option is omitted
when using the -d or -s options the default
idtype of pid is assumed.
The valid idtype arguments and corresponding
interpretations of idlist are as follows:
-i all The priocntl command applies to
all existing processes. No idlist
should be specified (if one is
specified, it is ignored). The
permission restrictions described
below still apply.
-i ctid idlist is a list of process con-
tract IDs. The priocntl command
applies to all processes with a
process contract ID equal to an ID
from the list.
SunOS 5.11 Last change: 1 Apr 2008 4
User Commands priocntl(1)
-i class idlist consists of a single class
name (RT for real-time, TS for
time-sharing, IA for inter-active,
FS for fair-share, or FX for
fixed-priority). The priocntl com-
mand applies to all processes in
the specified class.
-i gid idlist is a list of group IDs. The
priocntl command applies to all
processes with an effective group
ID equal to an ID from the list.
-i pgid idlist is a list of process group
IDs. The priocntl command applies
to all processes in the specified
process groups.
-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 pro-
cess ID is in the list.
-i projid idlist is a list of project IDs.
The priocntl command applies to
all processes with an effective
project ID equal to an ID from the
list.
-i sid idlist is a list of session IDs.
The priocntl command applies to
all processes in the specified
sessions.
-i taskid idlist is a list of task IDs. The
priocntl command applies to all
processes in the specified tasks.
-i uid idlist is a list of user IDs. The
priocntl command applies to all
SunOS 5.11 Last change: 1 Apr 2008 5
User Commands priocntl(1)
processes with an effective user
ID equal to an ID from the list.
-i zoneid idlist is a list of zone IDs. The
priocntl command applies to all
processes with an effective zone
ID equal to an ID from the list.
-l Displays a list of the classes currently con-
figured in the system along with class-specific
information about each class. The format of the
class-specific information displayed is
described under USAGE.
-s Sets the scheduling parameters associated with
a set of processes.
The valid class-specific options for setting real-time
parameters are:
-p rtpri Sets the real-time priority of the
specified process(es) to rtpri.
-t tqntm [-r res] Sets the time quantum of the specified
process(es) to tqntm. You can option-
ally specify a resolution as explained
below.
-q tqsig Sets the real-time time quantum signal
of the specified process(es) to tqsig.
The valid class-specific options for setting time-sharing
parameters are:
-m tsuprilim Sets the user priority limit of the speci-
fied process(es) to tsuprilim.
-p tsupri Sets the user priority of the specified
process(es) to tsupri.
SunOS 5.11 Last change: 1 Apr 2008 6
User Commands priocntl(1)
The valid class-specific options for setting inter-active
parameters are:
-m iauprilim Sets the user priority limit of the speci-
fied process(es) to iauprilim.
-p iaupri Sets the user priority of the specified
process(es) to iaupri.
The valid class-specific options for setting fair-share
parameters are:
-m fssuprilim Sets the user priority limit of the speci-
fied process(es) to fssuprilim.
-p fssupri Sets the user priority of the specified
process(es) to fssupri.
The valid class-specific options for setting fixed-priority
parameters are:
-m fxuprilim Sets the user priority limit of the speci-
fied process(es) to fxuprilim.
-p fxupri Sets the user priority of the specified
process(es) to fxupri.
-t tqntm [-r res] Sets the time quantum of the speci-
fied process(es) to tqntm. You can option-
ally specify a resolution as explained
below.
USAGE
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
ensures that a runnable real-time process is given CPU ser-
vice before any process belonging to any other class.
SunOS 5.11 Last change: 1 Apr 2008 7
User Commands priocntl(1)
The real-time class has a range of real-time priority
(rtpri) values that can 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 installation that has already configured a real-
time scheduler, 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 priori-
ties 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
provides for control over the length of the time quantum
allotted to processes in the real-time class. The time quan-
tum value specifies the maximum amount of time a process can
run, assuming that it does not complete or enter a resource
or event wait state (sleep). Notice that if another process
becomes runnable at a higher priority, the currently running
process can be preempted before receiving its full time
quantum.
The command
priocntl -d [-i idtype] [idlist]
displays the real-time priority, time quantum (in mil-
lisecond resolution), and time quantum signal value for each
real-time process in the set specified by idtype and idlist.
SunOS 5.11 Last change: 1 Apr 2008 8
User Commands priocntl(1)
Any combination of the -p, -t [-r], and -q options can 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 system configuration; see rtdptbl(4).
When using the -t tqntm option, you can optionally specify a
resolution using the -r res option. (If no resolution is
specified, millisecond resolution is assumed.) If res is
specified, it must be a positive integer between 1 and
1,000,000,000 inclusively 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 can be specified, the time quantum
length is rounded up by the system to the next integral mul-
tiple of the system clock's resolution. Requests for time
quantums of zero or quantums greater than the (typically
very large) implementation-specific maximum quantum result
in an error.
The real-time time quantum signal can be used to notify
runaway real-time processes about the consumption of their
time quantum. Those processes, which are monitored by the
real-time time quantum signal, receive the configured signal
in the event of time quantum expiration. The default value
(0) of the time quantum signal tqsig denotes no signal
delivery. A positive value denotes the delivery of the sig-
nal specified by the value. Like kill(1) and other commands
operating on signals, the -q tqsig option is also able to
handle symbolically named signals, like XCPU or KIL.
In order to change the class of a process to real-time (from
any other class), the user invoking priocntl must have
super-user privilege. 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, time quantum, and time quantum sig-
nal are inherited across the fork(2) and exec(2) system
SunOS 5.11 Last change: 1 Apr 2008 9
User Commands priocntl(1)
calls. When using the time quantum signal with a user
defined signal handler across the exec(2) system call, the
new image must install an appropriate user defined signal
handler before the time quantum expires. Otherwise, unpredi-
cable behavior would result.
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 objectives
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 can be assigned to processes
within the class. 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 runs 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 can 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 can be set for a given process.
The command
priocntl -d [-i idtype] [idlist]
SunOS 5.11 Last change: 1 Apr 2008 10
User Commands priocntl(1)
displays the user priority and user priority limit for each
time-sharing process in the set specified by idtype and
idlist.
Any time-sharing process can lower its own tsuprilim (or
that of another process with the same user ID). Only a
time-sharing process with super-user privilege can raise a
tsuprilim. When changing the class of a process to time-
sharing from some other class, super-user privilege is
required in order to set the initial tsuprilim to a value
greater than zero.
Any time-sharing process can 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 -m and -p options can 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 excep-
tion is when the -p option is omitted and -m 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 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.
Inter-Active Class
The inter-active scheduling policy provides for a fair and
effective allocation of the CPU resource among processes
with varying CPU consumption characteristics while providing
good responsiveness for user interaction. The objectives of
the inter-active policy are to provide good response time to
interactive processes and good throughput to CPU-bound jobs.
The priorities of processes in the inter-active class can be
changed in the same manner as those in the time-sharing
class, though the modified priorities continue to be
adjusted to provide good responsiveness for user interac-
tion.
SunOS 5.11 Last change: 1 Apr 2008 11
User Commands priocntl(1)
The inter-active user priority limit, iaupri, is equivalent
to tsupri. The inter-active per process user priority, iau-
prilim, is equivalent to tsuprilim.
Inter-active class processes that have the iamode ("interac-
tive mode") bit set are given a priority boost value of 10,
which is factored into the user mode priority of the process
when that calculation is made, that is, every time a
process's priority is adjusted. This feature is used by the
X windowing system, which sets this bit for those processes
that run inside of the current active window to give them a
higher priority.
Fair-Share Class
The fair-share scheduling policy provides a fair allocation
of system CPU resources among projects, independent of the
number of processes they own. Projects are given "shares" to
control their entitlement to CPU resources. Resource usage
is remembered over time, so that entitlement is reduced for
heavy usage, and increased for light usage, with respect to
other projects. CPU time is scheduled among processes
according to their owner's entitlements, independent of the
number of processes each project owns.
The FS scheduling class supports the notion of per-process
user priority and user priority limit for compatibility with
the time-share scheduler. The fair share scheduler attempts
to provide an evenly graded effect across the whole range of
user priorities. Processes with negative fssupri values
receive time slices less frequently than normal, while
processes with positive fssupri values receive time slices
more frequently than normal. Notice that user priorities
do not interfere with shares. That is, changing a fssupri
value of a process is not going to affect its project's
overall CPU usage which only relates to the amount of shares
it is allocated compared to other projects.
The priorities of processes in the fair-share class can be
changed in the same manner as those in the time-share class.
Fixed-Priority Class
The fixed-priority class provides a fixed priority preemp-
tive scheduling policy for those processes requiring that
the scheduling priorities do not get dynamically adjusted by
the system and that the user/application have control of the
scheduling priorities.
SunOS 5.11 Last change: 1 Apr 2008 12
User Commands priocntl(1)
The fixed-priority class shares the same range of scheduling
priorities with the time-sharing class, by default. The
fixed-priority class has a range of fixed-priority user
priority (fxupri) values that can be assigned to processes
within the class. User priorities range from 0 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
user/application control over the scheduling of processes in
the fixed-priority class. For processes in the fixed-
priority class, the fxupri value is, for all practical pur-
poses, equivalent to the scheduling priority of the pro-
cess. The fxupri value completely determines the scheduling
priority of a fixed-priority process relative to other
processes within its class. Numerically higher fxupri values
represent higher priorities.
In addition to the system-wide limits on user priority
(displayed with priocntl -l), there is a per process user
priority limit (fxuprilim), which specifies the maximum
fxupri value that can be set for a given process.
Any fixed-priority process can lower its own fxuprilim (or
that of another process with the same user ID). Only a pro-
cess with super-user privilege can raise a fxuprilim. When
changing the class of a process to fixed-priority from some
other class, super-user privilege is required in order to
set the initial fxuprilim to a value greater than zero.
Any fixed-priority process can set its own fxupri (or that
of another process with the same user ID) to any value less
than or equal to the process's fxuprilim. Attempts to set
the fxupri above the fxuprilim (or set the fxuprilim below
the fxupri) result in the fxupri being set equal to the
fxuprilim.
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
can run, before surrendering the CPU, assuming that it does
not complete or enter a resource or event wait state
SunOS 5.11 Last change: 1 Apr 2008 13
User Commands priocntl(1)
(sleep). Notice that if another process becomes runnable at
a higher priority, the currently running process can be
preempted before receiving its full time quantum.
Any combination of the -m, -p, and -t options can 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 normally unaf-
fected. The exception is when the -p option is omitted and
the -m option is used to set a fxuprilim below the current
fxupri. In this case, the fxupri is set equal to the fxupri-
lim which is being set. If an option is omitted when chang-
ing the class of a process to fixed-priority from some other
class, the associated parameter is set to a default value.
The default value for fxuprilim is 0. The default for fxupri
is to set it equal to the fxuprilim value which is being
set. The default for time quantum is dependent on the fxupri
and on the system configuration. See fxdptbl(4).
The time quantum of processes in the fixed-priority class
can be changed in the same manner as those in the real-time
class.
The fixed-priority user priority, user priority limit, and
time quantum are inherited across the fork(2) and exec(2)
system calls.
EXAMPLES
The following are real-time class examples:
Example 1 Setting the Class
The following example 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 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.
example% priocntl -s -c RT -t 1 -r 10 -i idtype idlist
Example 2 Executing a Command in Real-time
SunOS 5.11 Last change: 1 Apr 2008 14
User Commands priocntl(1)
The following example executes command in the real-time
class with a real-time priority of 15 and a time quantum of
20 milliseconds:
example% priocntl -e -c RT -p 15 -t 20 command
Example 3 Executing a Command in Real-time with a Specified
Quantum Signal
The following example executes command in the real-time
class with a real-time priority of 11, a time quantum of 250
milliseconds, and where the specified real-time quantum sig-
nal is SIGXCPU:
example% priocntl -e -c RT -p 11 -t 250 -q XCPU command
The following are time-sharing class examples:
Example 4 Setting the Class of non-time-sharing Processes
The following example 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.
example% priocntl -s -c TS -i idtype idlist
Example 5 Executing a Command in the Time-sharing Class
The following example executes command with the arguments
arguments in the time-sharing class with a user priority
limit of 0 and a user priority of -15:
example% priocntl -e -c TS -m 0 -p -15 command [arguments]
SunOS 5.11 Last change: 1 Apr 2008 15
User Commands priocntl(1)
Example 6 Executing a Command in Fixed-Priority Class
The following example executes a command in the fixed-
priority class with a user priority limit of 20 and user
priority of 10 and time quantum of 250 milliseconds:
example% priocntl -e -c FX -m 20 -p 10 -t 250 command
EXIT STATUS
The following exit values are returned:
For options -d, -l, and -s:
0 Successful operation.
1 Error condition.
For option -e:
Return of the Exit Status of the executed command denotes
successful operation. Otherwise,
1 Command could not be executed at the specified prior-
ity.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 1 Apr 2008 16
User Commands priocntl(1)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
CSI Enabled
SEE ALSO
kill(1), nice(1), ps(1), dispadmin(1M), exec(2), fork(2),
priocntl(2), fxdptbl(4), process(4), rtdptbl(4), attri-
butes(5), zones(5), FS(7)
System Administration Guide: Basic Administration
DIAGNOSTICS
priocntl prints the following error messages:
Process(es) not found
None of the specified processes exists.
Specified 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 specified.
Invalid option or argument
An unrecognized or invalid option or option argument is
used.
SunOS 5.11 Last change: 1 Apr 2008 17
|
