priocntl(2) UNIX System V 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(idtypet idtype, idt 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 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:
PPID id is a process ID specifying a single process to which the
priocntl system call is to apply.
PPPID
id is a parent process ID. The priocntl system call applies to all
processes with the specified parent process ID.
PPGID
id is a process group ID. The priocntl system call applies to all
processes in the specified process group.
PSID id is a session ID. The priocntl system call applies to all
processes in the specified session.
10/89 Page 1
priocntl(2) UNIX System V priocntl(2)
PCID id is a class ID (returned by priocntl PCGETCID as explained
below). The priocntl system call applies to all processes in the
specified class.
PUID id is a user ID. The priocntl system call applies to all processes
with this effective user ID.
PGID id is a group ID. The priocntl system call applies to all
processes with this effective group ID.
PALL 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 PMYID 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
PCSETPARMS 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 PUID 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 PCSETPARMS) 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.
The following structure is used by the PCGETCID and PCGETCLINFO
commands.
Page 2 10/89
priocntl(2) UNIX System V priocntl(2)
typedef struct {
idt pccid; /* Class id */
char pcclname[PCCLNMSZ]; /* Class name */
long pcclinfo[PCCLINFOSZ]; /* Class information */
} pcinfot;
pccid is a class ID returned by priocntl PCGETCID. pcclname is a
buffer of size PCCLNMSZ (defined in <sys/priocntl.h>) used to hold the
class name (RT for real-time or TS for time-sharing).
pcclinfo is a buffer of size PCCLINFOSZ (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 PCSETPARMS and PCGETPARMS
commands.
typedef struct {
idt pccid; /* Process class */
long pcclparms[PCCLPARMSZ]; /* Class-specific params */
} pcparmst;
pccid is a class ID (returned by priocntl PCGETCID). The special class
ID PCCLNULL can also be assigned to pccid when using the PCGETPARMS
command as explained below.
The pcclparms buffer holds class-specific scheduling parameters. The
format of this parameter data for a particular class is described under
the appropriate heading below. PCCLPARMSZ is the length of the
pcclparms buffer and is defined in <sys/priocntl.h>.
Commands
Available priocntl commands are:
PCGETCID
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 pcinfot. The pcclname buffer
contains the name of the class whose attributes you are getting.
On success, the class ID is returned in pccid, the class attributes
are returned in the pcclinfo buffer, and the priocntl call returns
the total number of classes configured in the system (including the
sys class). If the class specified by pcclname is invalid or is not
currently configured the priocntl call returns -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.
10/89 Page 3
priocntl(2) UNIX System V priocntl(2)
If arg is a NULL pointer, no attribute data is returned but the
priocntl call still returns the number of configured classes.
PCGETCLINFO
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 pcinfot. pccid is the class ID of the
class whose attributes you are getting.
On success, the class name is returned in the pcclname buffer, the
class attributes are returned in the pcclinfo 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.
PCSETPARMS
Set the class and class-specific scheduling parameters of the
specified process(es). arg points to a structure of type pcparmst.
pccid specifies the class you are setting and the pcclparms 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.
PCGETPARMS
Get the class and/or class-specific scheduling parameters of a
process. arg points the a structure of type pcparmst.
If pccid 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 pcclparms 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.
Page 4 10/89
priocntl(2) UNIX System V priocntl(2)
If pccid 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 pcclparms 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 pccid is PCCLNULL and a single process is specified the class of
the specified process is returned in pccid and its scheduling
parameters are returned in the pcclparms buffer.
PCADMIN
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 (rtpri) values
that may be assigned to processes within the class. Real-time priorities
range from 0 to x, where the value of x is configurable and can be
determined for a specific installation by using the priocntl PCGETCID or
PCGETCLINFO 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
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 may run assuming that it does not complete or enter a
10/89 Page 5
priocntl(2) UNIX System V priocntl(2)
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
rtpri 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 rtpri 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 rtmaxpri; /* Maximum real-time priority */
} rtinfot;
The priocntl PCGETCID and PCGETCLINFO commands return real-time class
attributes in the pcclinfo buffer in this format.
rtmaxpri specifies the configured maximum rtpri value for the real-time
class (if rtmaxpri 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.
typedef struct {
short rtpri; /* Real-Time priority */
ulong rttqsecs; /* Seconds in time quantum */
long rttqnsecs; /* Additional nanoseconds in quantum */
} rtparmst;
When using the priocntl PCSETPARMS or PCGETPARMS commands, if pccid
specifies the real-time class, the data in the pcclparms buffer is in
this format.
Page 6 10/89
priocntl(2) UNIX System V priocntl(2)
The above commands can be used to set the real-time priority to the
specified value or get the current rtpri value. Setting the rtpri
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 rtpri 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 rtpri 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 rtpri field should be set to the
special value RTNOCHANGE (defined in <sys/rtpriocntl.h>). Specifying
RTNOCHANGE 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 PCGETPARMS command, if pccid 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 rtpri 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 rttqsecs and rttqnsecs fields are used for getting or setting the
time quantum associated with a process or group of processes. rttqsecs
is the number of seconds in the time quantum and rttqnsecs is the number
of additional nanoseconds in the quantum. For example setting rttqsecs
to 2 and rttqnsecs 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 rttqnsecs field results in an error return with errno
set to EINVAL. Although the resolution of the tqnsecs 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 3B2 is 10
milliseconds (1 ``tick''). Setting rttqsecs to 0 and rttqnsecs to
34,000,000 would specify a time quantum of 34 milliseconds, which would
be rounded up to 4 ticks (40 milliseconds) on the 3B2. The maximum time
quantum that can be specified is implementation-specific and equal to
LONGMAX ticks (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
rttqsecs and rttqnsecs to 0) results in an error return with errno set
to EINVAL.
The rttqnsecs field can also be set to one of the following special
values (defined in <sys/rtpriocntl.h>), in which case the value of
rttqsecs is ignored.
10/89 Page 7
priocntl(2) UNIX System V priocntl(2)
RTTQINF Set an infinite time quantum.
RTTQDEF Set the time quantum to the default for this priority [see
rtdptbl(4)].
RTNOCHANGE
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 RTTQDEF.
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
tsupri below) values that may be assigned to processes within the class.
A tsupri 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 PCGETCID or PCGETCLINFO command.
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 process with a higher
tsupri value will run before one with a lower tsupri value. This is
because the tsupri value is just one factor used to determine the
scheduling priority of a time-sharing process. The system may
dynamically adjust the internal scheduling priority of a time-sharing
process based on other factors such as recent CPU usage.
In addition to the system-wide limits on user priority (returned by the
PCGETCID and PCGETCLINFO commands) there is a per process user priority
limit (see tsuprilim below), which specifies the maximum tsupri value
that may be set for a given process; by default, tsuprilim is zero.
Page 8 10/89
priocntl(2) UNIX System V priocntl(2)
The following structure (defined in <sys/tspriocntl.h>) defines the
format used for the attribute data for the time-sharing class.
typedef struct {
short tsmaxupri; /* Limits of user priority range */
} tsinfot;
The priocntl PCGETCID and PCGETCLINFO commands return time-sharing
class attributes in the pcclinfo buffer in this format.
tsmaxupri specifies the configured maximum user priority value for the
time-sharing class. If tsmaxupri 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 tsuprilim; /* Time-Sharing user priority limit */
short tsupri; /* Time-Sharing user priority */
} tsparmst;
When using the priocntl PCSETPARMS or PCGETPARMS commands, if pccid
specifies the time-sharing class, the data in the pcclparms buffer is in
this format.
For the priocntl PCGETPARMS command, if pccid 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
tsupri 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 one returned is
implementation-dependent.
Any time-sharing process may lower its own tsuprilim (or that of another
process with the same user ID). Only a time-sharing process with super-
user privileges may raise a tsuprilim. When changing the class of a
process to time-sharing from some other class, super-user privileges are
required in order to set the initial tsuprilim to a value greater than
zero. Attempts by a non-super-user process to raise a tsuprilim or set
an initial tsuprilim greater than zero fail with a return value of -1
and errno set to EPERM.
Any time-sharing process may set its own tsupri (or that of another
process with the same user ID) to any value less than or equal to the
process's tsuprilim. Attempts to set the tsupri above the tsuprilim
(and/or set the tsuprilim below the tsupri) result in the tsupri being
set equal to the tsuprilim.
10/89 Page 9
priocntl(2) UNIX System V priocntl(2)
Either of the tsuprilim or tsupri fields may be set to the special
value TSNOCHANGE (defined in <sys/tspriocntl.h>) in order to set one of
the values without affecting the other. Specifying TSNOCHANGE for the
tsupri when the tsuprilim is being set to a value below the current
tsupri causes the tsupri to be set equal to the tsuprilim being set.
Specifying TSNOCHANGE 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 tsuprilim is 0 and
the default for the tsupri is to set it equal to the tsuprilim which is
being set.
The time-sharing user priority and user priority limit are inherited
across the fork and exec 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.
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)
priocntl(1) in the User's Reference Manual
dispadmin(1M), rtdptbl(4), tsdptbl(4) in the System Administrator's
Reference Manual
Page 10 10/89