priocntl(2) priocntl(2)
NAME
priocntl - process scheduler control
SYNOPSIS
#include <sys/types.h>
#include <sys/priocntl.h>
#include <sys/rtpriocntl.h>
#include <sys/tspriocntl.h>
long priocntl(idtype_t idtype, id_t id, int cmd, ... /* arg */);
DESCRIPTION
priocntl provides for control over the scheduling of active
processes.
Processes fall into distinct classes with a separate scheduling
policy applied to each class. The two classes currently supported
are the real-time class and the time-sharing class. The
characteristics of these classes are described under the
corresponding headings below. The class attribute of a process is
inherited across the fork(2) and exec(2) system calls. priocntl can
be used to dynamically change the class and other scheduling
parameters associated with a running process or set of processes
given the appropriate permissions as explained below.
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.
priocntl provides an interface for specifying a process or set of
processes to which the system call is to apply. The priocntlset
system call provides the same functions as priocntl, but allows a
more general interface for specifying the set of processes to which
the system call is to apply.
For priocntl, the idtype and id arguments are used together to
specify the set of processes. The interpretation of id depends on
the value of idtype. The possible values for idtype and
corresponding interpretations of id are as follows:
P_PID id is a process ID specifying a single process to which the
priocntl system call is to apply.
P_PPID
id is a parent process ID. The priocntl system call applies to
all processes with the specified parent process ID.
P_PGID
id is a process group ID. The priocntl system call applies to
all processes in the specified process group.
7/91 Page 1
priocntl(2) priocntl(2)
P_SID id is a session ID. The priocntl system call applies to all
processes in the specified session.
P_CID id is a class ID (returned by priocntl PC_GETCID as explained
below). The priocntl system call applies to all processes in
the specified class.
P_UID id is a user ID. The priocntl system call applies to all
processes with this effective user ID.
P_GID id is a group ID. The priocntl system call applies to all
processes with this effective group ID.
P_ALL The priocntl system call applies to all existing processes.
The value of id is ignored. The permission restrictions
described below still apply.
An id value of P_MYID can be used in conjunction with the idtype
value to specify the calling process's process ID, parent process ID,
process group ID, session ID, class ID, user ID, or group ID.
In order to change the scheduling parameters of a process (using the
PC_SETPARMS command as explained below) the real or effective user ID
of the process calling priocntl must match the real or effective user
ID of the receiving process or the effective user ID of the calling
process 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 and/or when setting class-specific scheduling parameters.
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 a specified set of processes are disregarded by priocntl.
For example, an idtype of P_UID and an id value of zero would specify
all processes with a user ID of zero except processes in the sys
class and (if changing the parameters using PC_SETPARMS) the init
process.
The init process is a special case. In order for a priocntl call to
change the class or other scheduling parameters of the init process
(process ID 1), it must be the only process specified by idtype and
id. The init process may be assigned to any class configured on the
system, but the time-sharing class is almost always the appropriate
choice. (Other choices may be highly undesirable; see the System
Administrator's Guide for more information.)
The data type and value of arg are specific to the type of command
specified by cmd.
Page 2 7/91
priocntl(2) priocntl(2)
The following structure is used by the PC_GETCID and PC_GETCLINFO
commands.
typedef struct {
id_t pc_cid; /* Class id */
char pc_clname[PC_CLNMSZ]; /* Class name */
long pc_clinfo[PC_CLINFOSZ]; /* Class information */
} pcinfo_t;
pc_cid is a class ID returned by priocntl PC_GETCID. pc_clname is a
buffer of size PC_CLNMSZ (defined in <sys/priocntl.h>) used to hold
the class name (RT for real-time or TS for time-sharing).
pc_clinfo is a buffer of size PC_CLINFOSZ (defined in
<sys/priocntl.h>) used to return data describing the attributes of a
specific class. The format of this data is class-specific and is
described under the appropriate heading (REAL-TIME CLASS or TIME-
SHARING CLASS) below.
The following structure is used by the PC_SETPARMS and PC_GETPARMS
commands.
typedef struct {
id_t pc_cid; /* Process class */
long pc_clparms[PC_CLPARMSZ]; /* Class-specific params */
} pcparms_t;
pc_cid is a class ID (returned by priocntl PC_GETCID). The special
class ID PC_CLNULL can also be assigned to pc_cid when using the
PC_GETPARMS command as explained below.
The pc_clparms buffer holds class-specific scheduling parameters.
The format of this parameter data for a particular class is described
under the appropriate heading below. PC_CLPARMSZ is the length of
the pc_clparms buffer and is defined in <sys/priocntl.h>.
Commands
Available priocntl commands are:
PC_GETCID
Get class ID and class attributes for a specific class given class
name. The idtype and id arguments are ignored. If arg is non-
null, it points to a structure of type pcinfo_t. The pc_clname
buffer contains the name of the class whose attributes you are
getting.
On success, the class ID is returned in pc_cid, the class
attributes are returned in the pc_clinfo buffer, and the priocntl
call returns the total number of classes configured in the system
(including the sys class). If the class specified by pc_clname is
invalid or is not currently configured the priocntl call returns
7/91 Page 3
priocntl(2) priocntl(2)
-1 with errno set to EINVAL. The format of the attribute data
returned for a given class is defined in the <sys/rtpriocntl.h> or
<sys/tspriocntl.h> header file and described under the appropriate
heading below.
If arg is a NULL pointer, no attribute data is returned but the
priocntl call still returns the number of configured classes.
PC_GETCLINFO
Get class name and class attributes for a specific class given
class ID. The idtype and id arguments are ignored. If arg is
non-null, it points to a structure of type pcinfo_t. pc_cid is
the class ID of the class whose attributes you are getting.
On success, the class name is returned in the pc_clname buffer,
the class attributes are returned in the pc_clinfo buffer, and the
priocntl call returns the total number of classes configured in
the system (including the sys class). The format of the attribute
data returned for a given class is defined in the
<sys/rtpriocntl.h> or <sys/tspriocntl.h> header file and described
under the appropriate heading below.
If arg is a NULL pointer, no attribute data is returned but the
priocntl call still returns the number of configured classes.
PC_SETPARMS
Set the class and class-specific scheduling parameters of the
specified process(es). arg points to a structure of type
pcparms_t. pc_cid specifies the class you are setting and the
pc_clparms buffer contains the class-specific parameters you are
setting. The format of the class-specific parameter data is
defined in the <sys/rtpriocntl.h> or <sys/tspriocntl.h> header
file and described under the appropriate class heading below.
When setting parameters for 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 may or may not continue through the set of
processes, depending on the nature of the error. If the error is
related to permissions (EPERM), priocntl continues through the
process set, resetting the parameters for all target processes for
which the calling process has appropriate permissions. priocntl
then returns -1 with errno set to EPERM to indicate that the
operation failed for one or more of the target processes. If
priocntl encounters an error other than permissions, it does not
continue through the set of target processes but returns the error
immediately.
PC_GETPARMS
Get the class and/or class-specific scheduling parameters of a
process. arg points to a structure of type pcparms_t.
Page 4 7/91
priocntl(2) priocntl(2)
If pc_cid specifies a configured class and a single process
belonging to that class is specified by the idtype and id values
or the procset structure, then the scheduling parameters of that
process are returned in the pc_clparms buffer. If the process
specified does not exist or does not belong to the specified
class, the priocntl call returns -1 with errno set to ESRCH.
If pc_cid specifies a configured class and a set of processes is
specified, the scheduling parameters of one of the specified
processes belonging to the specified class are returned in the
pc_clparms buffer and the priocntl call returns the process ID of
the selected process. The criteria for selecting a process to
return in this case is class dependent. If none of the specified
processes exist or none of them belong to the specified class the
priocntl call returns -1 with errno set to ESRCH.
If pc_cid is PC_CLNULL and a single process is specified the class
of the specified process is returned in pc_cid and its scheduling
parameters are returned in the pc_clparms buffer.
PC_ADMIN
This command provides functionality needed for the implementation
of the dispadmin(1M) command. It is not intended for general use
by other applications.
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 (rt_pri) 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 determined for a specific installation by using the
priocntl PC_GETCID or PC_GETCLINFO command.
The real-time scheduling policy is a fixed priority policy. The
scheduling priority of a real-time process is never changed except as
the result of an explicit request by the user/application to change
the rt_pri value of the process.
For processes in the real-time class, the rt_pri value is, for all
practical purposes, equivalent to the scheduling priority of the
process. The rt_pri value completely determines the scheduling
priority of a real-time process relative to other processes within
its class. Numerically higher rt_pri values represent higher
priorities. Since the real-time class controls the highest range of
7/91 Page 5
priocntl(2) priocntl(2)
scheduling priorities in the system it is guaranteed that the
runnable real-time process with the highest rt_pri 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 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 system's process scheduler keeps the runnable real-time processes
on a set of scheduling queues. There is a separate queue for each
configured real-time priority and all real-time processes with a
given rt_pri value are kept together on the appropriate queue. The
processes on a given queue are ordered in FIFO order (that is, the
process at the front of the queue has been waiting longest for
service and receives the CPU first). Real-time processes that wake
up after sleeping, processes which change to the real-time class from
some other class, processes which have used their full time quantum,
and runnable processes whose priority is reset by priocntl are all
placed at the back of the appropriate queue for their priority. A
process that is preempted by a higher priority process remains at the
front of the queue (with whatever time is remaining in its time
quantum) and runs before any other process at this priority.
Following a fork(2) system call by a real-time process, the parent
process continues to run while the child process (which inherits its
parent's rt_pri value) is placed at the back of the queue.
The following structure (defined in <sys/rtpriocntl.h>) defines the
format used for the attribute data for the real-time class.
typedef struct {
short rt_maxpri; /* Maximum real-time priority */
} rtinfo_t;
The priocntl PC_GETCID and PC_GETCLINFO commands return real-time
class attributes in the pc_clinfo buffer in this format.
rt_maxpri specifies the configured maximum rt_pri value for the
real-time class (if rt_maxpri is x, the valid real-time priorities
range from 0 to x).
The following structure (defined in <sys/rtpriocntl.h>) defines the
format used to specify the real-time class-specific scheduling
parameters of a process.
Page 6 7/91
priocntl(2) priocntl(2)
typedef struct {
short rt_pri; /* Real-Time priority */
me quantum */
long rt_tqnsecs; /* Additional nanoseconds in quantum */
} rtparms_t;
When using the priocntl PC_SETPARMS or PC_GETPARMS commands, if
pc_cid specifies the real-time class, the data in the pc_clparms
buffer is in this format.
The above commands can be used to set the real-time priority to the
specified value or get the current rt_pri value. Setting the rt_pri
value of a process that is currently running or runnable (not
sleeping) causes the process to be placed at the back of the
scheduling queue for the specified priority. The process is placed
at the back of the appropriate queue regardless of whether the
priority being set is different from the previous rt_pri value of the
process. Note that a running process can voluntarily release the CPU
and go to the back of the scheduling queue at the same priority by
resetting its rt_pri value to its current real-time priority value.
In order to change the time quantum of a process without setting the
priority or affecting the process's position on the queue, the rt_pri
field should be set to the special value RT_NOCHANGE (defined in
<sys/rtpriocntl.h>). Specifying RT_NOCHANGE when changing the class
of a process to real-time from some other class results in the real-
time priority being set to zero.
For the priocntl PC_GETPARMS command, if pc_cid specifies the real-
time class and more than one real-time process is specified, the
scheduling parameters of the real-time process with the highest
rt_pri value among the specified processes are returned and the
process ID of this process is returned by the priocntl call. If
there is more than one process sharing the highest priority, the one
returned is implementation-dependent.
The rt_tqsecs and rt_tqnsecs fields are used for getting or setting
the time quantum associated with a process or group of processes.
rt_tqsecs is the number of seconds in the time quantum and rt_tqnsecs
is the number of additional nanoseconds in the quantum. For example
setting rt_tqsecs to 2 and rt_tqnsecs to 500,000,000 (decimal) would
result in a time quantum of two and one-half seconds. Specifying a
value of 1,000,000,000 or greater in the rt_tqnsecs field results in
an error return with errno set to EINVAL. Although the resolution of
the tq_nsecs field is very fine, the specified time quantum length is
rounded up by the system to the next integral multiple of the system
clock's resolution. For example, the finest resolution currently
available on the delta box is 10 milliseconds (1 ``tick''). Setting
rt_tqsecs to 0 and rt_tqnsecs to 34,000,000 would specify a time
quantum of 34 milliseconds, which would be rounded up to 4 ticks (40
milliseconds) on the delta box. The maximum time quantum that can be
specified is implementation-specific and equal to LONG_MAX ticks
7/91 Page 7
priocntl(2) priocntl(2)
(defined in <limits.h>). Requesting a quantum greater than this
maximum results in an error return with errno set to ERANGE (although
infinite quantums may be requested using a special value as explained
below). Requesting a time quantum of zero (setting both rt_tqsecs
and rt_tqnsecs to 0) results in an error return with errno set to
EINVAL.
The rt_tqnsecs field can also be set to one of the following special
values (defined in <sys/rtpriocntl.h>), in which case the value of
rt_tqsecs is ignored.
RT_TQINF Set an infinite time quantum.
RT_TQDEF Set the time quantum to the default for this priority
[see rt_dptbl(4)].
RT_NOCHANGE
Don't set the time quantum. This value is useful when
you wish to change the real-time priority of a process
without affecting the time quantum. Specifying this
value when changing the class of a process to real-time
from some other class is equivalent to specifying
RT_TQDEF.
In order to change the class of a process to real-time (from any
other class) the process invoking priocntl must have super-user
privileges. In order to change the priority or time quantum setting
of a real-time process the process invoking priocntl must have
super-user privileges or must itself be a real-time process whose
real or effective user ID matches the real of effective user ID of
the target process.
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 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 (see
ts_upri below) values that may be assigned to processes within the
class. A ts_upri value of zero is defined as the default base
priority for the time-sharing class. User priorities range from -x
to +x where the value of x is configurable and can be determined for
a specific installation by using the priocntl PC_GETCID or
PC_GETCLINFO command.
Page 8 7/91
priocntl(2) priocntl(2)
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 ts_upri 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
process with a higher ts_upri value will run before one with a lower
ts_upri value. This is because the ts_upri 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 (returned by
the PC_GETCID and PC_GETCLINFO commands) there is a per process user
priority limit (see ts_uprilim below), which specifies the maximum
ts_upri value that may be set for a given process; by default,
ts_uprilim is zero.
The following structure (defined in <sys/tspriocntl.h>) defines the
format used for the attribute data for the time-sharing class.
typedef struct {
short ts_maxupri; /* Limits of user priority range */
} tsinfo_t;
The priocntl PC_GETCID and PC_GETCLINFO commands return time-sharing
class attributes in the pc_clinfo buffer in this format.
ts_maxupri specifies the configured maximum user priority value for
the time-sharing class. If ts_maxupri is x, the valid range for both
user priorities and user priority limits is from -x to +x.
The following structure (defined in <sys/tspriocntl.h>) defines the
format used to specify the time-sharing class-specific scheduling
parameters of a process.
typedef struct {
short ts_uprilim; /* Time-Sharing user priority limit */
short ts_upri; /* Time-Sharing user priority */
} tsparms_t;
When using the priocntl PC_SETPARMS or PC_GETPARMS commands, if
pc_cid specifies the time-sharing class, the data in the pc_clparms
buffer is in this format.
For the priocntl PC_GETPARMS command, if pc_cid specifies the time-
sharing class and more than one time-sharing process is specified,
the scheduling parameters of the time-sharing process with the
highest ts_upri value among the specified processes is returned and
the process ID of this process is returned by the priocntl call. If
there is more than one process sharing the highest user priority, the
7/91 Page 9
priocntl(2) priocntl(2)
one returned is implementation-dependent.
Any time-sharing process may lower its own ts_uprilim (or that of
another process with the same user ID). Only a time-sharing process
with super-user privileges may raise a ts_uprilim. 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 ts_uprilim to a
value greater than zero. Attempts by a non-super-user process to
raise a ts_uprilim or set an initial ts_uprilim greater than zero
fail with a return value of -1 and e
lim. Attempts to set the ts_upri above the
ts_uprilim (and/or set the ts_uprilim below the ts_upri) result in
the ts_upri being set equal to the ts_uprilim.
Either of the ts_uprilim or ts_upri fields may be set to the special
value TS_NOCHANGE (defined in <sys/tspriocntl.h>) in order to set one
of the values without affecting the other. Specifying TS_NOCHANGE
for the ts_upri when the ts_uprilim is being set to a value below the
current ts_upri causes the ts_upri to be set equal to the ts_uprilim
being set. Specifying TS_NOCHANGE for a parameter when changing the
class of a process to time-sharing (from some other class) causes the
parameter to be set to a default value. The default value for the
ts_uprilim is 0 and the default for the ts_upri is to set it equal to
the ts_uprilim which is being set.
The time-sharing user priority and user priority limit are inherited
across the fork(2) and exec(2) system calls.
RETURN VALUE
Unless otherwise noted above, priocntl returns a value of 0 on
success. priocntl returns -1 on failure and sets errno to indicate
the error.
ERRORS
priocntl fails if one or more of the following are true :
EPERM The calling process does not have the required permissions as
explained above.
EINVAL The argument cmd was invalid, an invalid or unconfigured
class was specified, or one of the parameters specified was
invalid.
ERANGE The requested time quantum is out of range.
ESRCH None of the specified processes exist.
Page 10 7/91
priocntl(2) priocntl(2)
EFAULT All or part of the area pointed to by one of the data
pointers is outside the process's address space.
ENOMEM An attempt to change the class of a process failed because of
insufficient memory.
EAGAIN An attempt to change the class of a process failed because of
insufficient resources other than memory (for example,
class-specific kernel data structures).
SEE ALSO
fork(2), exec(2), nice(2), priocntlset(2) rt_dptbl(4), ts_dptbl(4).
priocntl(1) in the User's Reference Manual .
dispadmin(1M) in the System Administrator's Reference Manual
7/91 Page 11