PRIOCNTL(1) 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 process scheduler or
execute a command with specified scheduling 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 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 specified
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, FSS 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 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 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 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
can 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 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...]


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, FSS for fair-share, or FX for fixed-
priority.) If the specified 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 contract IDs.
The priocntl command applies to all
processes with a process contract ID equal
to an ID from the list.


-i class
idlist consists of a single class name (RT
for real-time, TS for time-sharing, IA for
inter-active, FSS for fair-share, or FX for
fixed-priority). The priocntl command
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 process 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 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 configured 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 optionally 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 specified
process(es) to tsuprilim.


-p tsupri
Sets the user priority of the specified process(es)
to tsupri.


The valid class-specific options for setting inter-active parameters
are:

-m iauprilim
Sets the user priority limit of the specified
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 specified
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 specified
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 specified
process(es) to tqntm. You can optionally 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 configured 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 service before any process belonging to any other class.


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 determines the scheduling
priority of a real-time process relative 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 provides for
control over the length of the time quantum allotted to processes in
the real-time class. The time quantum 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 millisecond
resolution), and time quantum signal value for each real-time process
in the set specified by idtype and idlist.


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 rt_dptbl(5).


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 multiple 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 signal 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 KILL.


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 effective user ID of the target process.


The real-time priority, time quantum, and time quantum signal are
inherited across the fork(2) and exec(2) system 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,
unpredictable 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]


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 exception 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 interaction.


The inter-active user priority limit, iaupri, is equivalent to
tsupri. The inter-active per process user priority, iauprilim, is
equivalent to tsuprilim.


Inter-active class processes that have the iamode ("interactive
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 FSS 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 preemptive
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.


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 purposes, equivalent to the scheduling priority of the
process. 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 process 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 (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 unaffected. 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 fxuprilim which is being set. If an option is omitted when
changing 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 fx_dptbl(5).


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

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 signal 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]

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 priority.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|CSI | Enabled |
+---------------+-----------------+

SEE ALSO

kill(1), nice(1), ps(1), exec(2), fork(2), priocntl(2), FSS(4),
fx_dptbl(5), process(5), rt_dptbl(5), attributes(7), zones(7),
dispadmin(8)


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.


April 1, 2008 PRIOCNTL(1)