priocntl(2)priocntl(2)NAMEpriocntl - manage scheduling properties of process
SYNOPSIS
#include <sys/types.h> #include <sys/priocntl.h> #include <sys/rtprioc‐
ntl.h> #include <sys/tspriocntl.h>
long priocntl(
idtype_t idtype,
id_t id,
int cmd,
void *arg );
PARAMETERS
Identifies the type of process to be affected. It is used with the id
parameter to specify the process or group of processes that will
change. Specifies the process ID, parent process ID, process group ID,
session ID, class ID, user ID, or group ID of a process or group of
processes. It is used with the idtype parameter. Specifies the how
the process or group of processes are affected. Specifies a pointer to
a structure.
DESCRIPTION
The priocntl function is used to change the class, priority, and other
scheduling properties of one or more active processes. Processes are
divided into four classes: real-time, time-sharing, POSIX round robin,
and the POSIX fifo class. Although the class and attributes of a
process within a class can change, each class has predefined scheduling
properties that cannot change.
To identify a process or set of processes that you want to change, you
must specify the id and idtype parameters. The cmd parameter defines
how the process or set of processes is to be affected. Depending on
which cmd parameter you select, the data type and value for the arg
parameter differs.
This discussion of the priocntl function is divided into the following
sections: Process Selection Command Descriptions Command Arguments
Scheduling and Priority Classes Include Files
The RESTRICTIONS section additionally describes instances in which a
class or process may not change.
Process Selection
Using the idtype and id parameters, you can specify a group or group of
processes that are to be affected by the priocntl function. The defi‐
nition of the id parameter is determined by the value of the idtype
parameter as follows:
───────────────────────────────────────────────────────
idtype id
───────────────────────────────────────────────────────
P_PID Defines id as a process ID. A single process
with this process ID is targeted.
P_PPID Defines id as a parent process ID. All pro‐
cesses with this specific parent process ID
are targeted.
P_PGID Defines id as a process group ID. All pro‐
cesses with this specific process group ID
are targeted.
P_SID Defines id as a session ID. All processes
within the specified session are targeted.
P_CID Defines id as a class ID. All processes
within the specified class are targeted.
P_UID Defines id as a user ID. All processes
within the effective user ID are targeted.
P_GID Defines id as a group ID. All processes
within the effective group ID are targeted.
P_ALL The value of id is ignored. All existing
processes are targeted for change. See the
RESTRICTIONS section for exceptions.
───────────────────────────────────────────────────────
The id parameter can also specify the value P_MYID which, when used
with the idtype parameter, specifies the calling process's process ID,
parent process ID, process group ID, session ID, class ID, user ID, or
group ID.
Command Descriptions
The five commands currently supported by the priocntl function are as
follows: Retrieves the class ID and class attributes for a specific
class given the class name. The idtype and id arguments are ignored.
If the value of the arg parameter is non-null, the class ID and
attribute data are returned in a pcinfo_t structure that is discussed
in the next subsection. If the value of the arg parameter is null,
attribute data is not returned, but the priocntl function does return
the configured number of classes. Retrieves the class name and class
attributes for a specific class given the class ID. The idtype and id
arguments are ignored. If the value of the arg is non-null, the class
name and attribute data is returned in a pcinfo_t structure that is
discussed in the next subsection. If the value of the arg parameter is
null, attribute data is not returned, but the priocntl function returns
the configured number of classes (including the sys class). Sets the
class and class-specific scheduling parameters of the process or pro‐
cesses specified by the id and idtype parameters. The arg parameter is
a pointer to a pcparms_t structure that is discussed in the next sub‐
section. Retrieves either the class or class-specific scheduling
parameters of a process or both. The process type is specified by the
id and idtype parameters. The arg parameter points to a pcparms_t
structure that is discussed in the next subsection. Specified for use
by a specific command and is not intended for general use by any other
application.
Command Arguments
The data type and value of the arg parameter is specific to the type of
command specified by the cmd parameter. This section highlights the
value for the arg parameter as it pertains to the commands.
For both the PC_GETCID and PC_GETCLINFO commands, the arg parameter if
not null, points to the following structure:
typedef struct {
id_t pc_cid;
char pc_clname[PC_CLNMSZ];
long pc_clinfo[PC_CLINFOSZ]; } pcinfo_t;
For the PC_GETCID command, the pc_cid field specifies the class ID on
return. The pc_clname field specifies the name of the class whose
attributes you are retrieving. The pc_clinfo field specifies the class
attributes on return. The format of the attribute data that is returned
is defined by the <sys/rtpriocntl.h> or the <sys/tspriocntl.h> header
files.
For the PC_GETCINFO command, the pc_cid field specifies the class ID of
the class whose attributes you are retrieving. The pc_clname field
specifies the class name on return. The pc_clinfo field specifies the
class attributes on return. The format of the attribute data that is
returned is defined by the <sys/rtpriocntl.h> or the <sys/tspriocntl.h>
header files.
For both the PC_SETPARMS and PC_GETPARMS command, the arg parameter
points to the following structure:
typedef struct {
id_t pc_cid;
char pc_clparms[PC_CLPARMSZ]; } pcparms_t;
For PC_SETPARMS, the pc_cid field specifies the class ID that you want
to set. The pc_clparms field contains the class specific parameters you
are setting. The PC_CLPARMSZ argument specifies the length of
pc_clparms field and is defined in <sys/priocntl.h>. The format of the
class specific data is defined by the <sys/rtpriocntl.h> or <sys/tspri‐
ocntl.h> header file. These formats are discussed in more detail under
the discussion of the available classes.
For the PC_GETPARMS command, the pc_cid field specifies the class ID.
This is the class ID returned by the priocntl PC_GETCID request. The
special class ID PC_CLNULL may also be assigned to the pc_cid parame‐
ter. The pc_pcparms field specifies the buffer that contains the class-
specific scheduling parameters. The PC_CLPARMSZ argument specifies the
length of pc_clparms buffer and is defined in <sys/priocntl.h>. The
format of the class specific data is defined by the <sys/rtpriocntl.h>
or <sys/tspriocntl.h> header file. These formats are discussed in more
detail under the discussion of the available classes.
For the PC_GETPARMS command, the contents of the pc_clparms field is
determined by the contents of the pc_cid field as follows: If the
pc_cid field specifies a configured class and the process that belongs
to that class was specified by the idtype and the id parameters or by
the procset structure, the pc_clparms field contains the scheduling
parameters of that process. If the process does not exist or the
process does not belong to the specified class, the priocntl function
returns the value -1 with errno set to [ESRCH]. If the pc_cid field
specifies a configured class and a set of processes is specified, only
the scheduling parameters of one process belonging to the specified
class is returned in this field. The priocntl function returns the
process ID of the selected process. In this instance, selecting a
process to return is class-dependent. If the specified process does
not exist, or if none of the processes belongs to the specified class,
the priocntl function returns the value -1 with errno set to [ESRCH].
If the pc_cid field contains PC_CLNULL and a single process is speci‐
fied, the class of the specified process is returned in the pc_cid
field and its scheduling parameters are returned in the pc_clparms
field. If this special class ID and a single process is specified, the
class of the specified process is returned in the pc_cid field and the
scheduling parameters are returned in the pc_clparms field.
Scheduling and Priority Classes
There are four types of classifications that can be used when managing
the scheduling priorities of a process or set of processes. These
classes are the real-time, time-sharing, POSIX round-robin, and the
POSIX fifo classes discussed in the next sections.
Real-time Class
Processes that require quick response and complete control of its
scheduling priorities through the user or application are placed in
this class. The real-time class provides a fixed scheduling policy
that can only be changed by an explicit request from either the user or
application. If this class is configured on the system, any running
real-time process should obtain the services of the CPU before a
process that belongs to another class.
To distinguish the priority of processes within the real-time class,
all processes are assigned a priority value. A priority value can
range from zero (0) to x, where x is a configurable value that can be
specified for a specific installation using the PC_GETCID or PC_GET‐
CLINFO commands. The higher the numerical priority value of a process,
the higher its priority on the system.
Each priority value that is configured into the system has a separate
scheduling queue that the system's process scheduler manages. Processes
with the same priority value share the same scheduling queue. All pro‐
cesses within a queue are placed in First-In-First-Out (FIFO) order.
The priocntl function not only controls priority, it also controls the
time quantum that is allotted to a process in the real-time class. The
time quantum value determines the maximum time that a running process
which has not entered a resource or event wait state (sleep) may run.
Note that regardless of the time quantum specified, if another process
at a higher priority makes a request to run, a running process may be
preempted before receiving its full time quantum. A process that is
preempted by a higher priority process remains first its scheduling
queue with the remainder of its specified time quantum still available.
Note that after a fork system call by a real-time time process, the
parent process continues to run while the child process inherits the
priority value of the parent and is placed at the back of the queue.
The structures used by the real time class to define the scheduling
priorities and class attributes of a process are discussed in the sec‐
tion on Include Files.
To change the class of a process to real-time (from any other class)
the process invoking the priocntl function must have superuser privi‐
leges. In order to change the priority or time quantum setting of a
real-time process the process invoking the priocntl function must have
superuser privileges or must itself be a real-time process whose real
or effective user ID matches the real of effective user ID of the tar‐
get process.
The real-time priority and time quantum are inherited
Time-Sharing Class
Processes that vary in CPU consumption, but which still require a rea‐
sonable response time with some user or application control over sched‐
uling should be placed in this class. To determine the scheduling of
processes within the time-sharing class, a user priority value is
assigned to a process. This value may range from -x to +x, where the
value of x is configurable and may be determined for a specific instal‐
lation using the PC_CID or PC_GETCLINFO commands.
Typically, a process with a higher user priority runs before a process
with a lower user priority allowing some control over the scheduling of
processes in this class. However, other factors also affect the prior‐
ity of a process in this class such as the amount of CPU usage already
expended by a process. There is also a per process user priority limit
that can be set for a given process.
The structures used by the time sharing class to define the scheduling
priorities and class attributes of a process are discussed in the sec‐
tion on Include Files.
POSIX Round Robin Class
This class is the same as the real-time class when a finite time quan‐
tum is specified. The POSIX round-robin class uses the same structures
as the real-time class to define the scheduling priorities and
attributes of a process.
To set or request the scheduling parameters for a POSIX round robin
class, only one process can be selected. If more than one process is
selected, all POSIX processes are ignored. This is true even when all
of the processes in the specified set belong to the POSIX round-robin
scheduling class.
The priority value for a processes in this class has the range -20 to
20. The time quantum must be a valid time quantum value and not a
reserved value as discussed in the Include Files section.
POSIX Fifo Class
This class is the same as the real-time class when an infinite time
quantum is specified. The POSIX fifo class uses the same structures as
the real-time class to define the scheduling priorities and attributes
of a process.
To set or request the scheduling parameters for a POSIX fifo class,
only one process can be selected. If more than one process is
selected, all POSIX processes are ignored. This is true even when all
of the processes in the specified set belong to the POSIX fifo schedul‐
ing class.
The priority value specified for processes has the range -20, 20. There
are restrictions set on the usage of the time quantum field as dis‐
cussed in the Include Files section.
Include Files
The real-time, POSIX round robin, and POSIX fifo classes use structures
defined in <sys/rtpriocntl.h> to define the format and class specific
priorities of a process. The time sharing class uses the structures
defined in <sys/tspriocntl.h> to define the format and class specific
priorities of a process.
These structures are defined in the next two sections.
The rtpriocntl.h Header File
The PC_GETCID and PC_GETCLINFO commands return real time class
attributes in the pc_clinfo buffer in using the following format:
typedef struct {
short rt_maxpri; /* Maximum real-time priority */ } rtinfo_t;
The rt_maxpri field specifies the configured maximum priority value
(rt_pri) for the real time class. For example, if rt_maxpri is x, the
valid real time priorities range from zero (0) to x).
If you use the PC_SETPARMS or PC_GETPARMS commands and the pc_cid buf‐
fer specifies the real-time class, the data in the pc_clparms buffer is
in the following format:
typedef struct {
short rt_pri; /* Real-Time priority */
ulong rt_tqsecs; /* Seconds in time quantum */
long rt_tqnsecs;/* Additional nanoseconds in quantum */ }
rtparms_t;
Used, depending on the command specified, to either set the real time
priority value or to get the current real time priority value.
If the real time priority value of a running or runnable process
is set, this causes the process to be placed at the back of the
scheduling queue for the specified priority regardless of the
previous priority value setting. Note that a running process
can release the CPU and return to the back of the scheduling
queue by resetting its priority value to its current real time
priority value.
When getting the real time priority value, if the pc_cid field
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 priority value of the set is returned
adn the process ID of this process is returned by the priocntl
function. If more than one process shares the highest priority,
the one returned is implementation-dependent
Note that you can change the time quantum of a process without
setting the priority or affecting the process's position on the
queue. In this instance, the rt_pri field should be set to the
reserved value RT_NOCHANGE defined below. Specifying this value
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. Used, depending on the command specified, to set
or get the time quantum associated with a process or group of
processes.
The rt_tqsecs field specifies the number of seconds in the time
quantum. Used, depending on the command specified, to set or
get the time quantum associated with a process or group of pro‐
cesses.
The rt_tqnsecs field specifies the number of additional nanosec‐
onds in the quantum. Specifying a value that exceeds 999,999,999
in the rt_tqnsecs field results in an error. For rt_tqnsecs,
the specified time quantum length is rounded up by the system to
the next integral multiple of the system clock's resolution.
The maximum time quantum that can be specified is implementa‐
tion-specific and equal to LONG_MAX ticks which is defined in
<sys/time>. Requesting a time quantum greater than the maximum
results in error. Requesting a time quantum of zero by setting
both rt_tqsecs and rt_tqnsecs to zero results in an error.
The rt_tqnsecs field can also be set to one of the following
reserved values (defined in <sys/rtpriocntl.h>). If one of these
values is specified, rt_tqsecs is ignored. Note that these val‐
ues may not be used if your process or process is in the POSIX
round robin class: Sets an infinite time quantum. This must be
used if you have selected the POSIX fifo class for your process
or processes. Sets the time quantum to the default for this
priority. Does not set a 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.
Setup of Structures in tspriocntl.h
The PC_GETCID and PC_GETCLINFO commands return time-sharing class
attributes in the pc_clinfo buffer in the following format:
typedef struct {
short ts_maxupri; /* Limits of user priority range */ } tsinfo_t;
The ts_maxupri field specifies the configured maximum user priority
value for the time-sharing class. If the ts_maxupri field is 2x1, the
valid range for both user priorities and user priority limits is from
-x to +x.
If you use the PC_SETPARMS or PC_GETPARMS commands and the pc_cid buf‐
fer specifies the time sharing class, the data in the pc_clparms buffer
is in the following format:
typedef struct {
short ts_uprilim; /* Time-Sharing user priority limit */
short ts_upri; /* Time-Sharing user priority */ } tsparms_t;
Specifies the maximum user priority limit for a process or set of pro‐
cesses.
All time sharing processes can lower its own ts_uprilim value
(or that of another process with the same user ID). Only a time-
sharing process with superuser privileges can increase this
value.
If changing the class of a process to the time sharing class
from some other class, superuser privileges are required to set
the initial ts_uprilim to a value greater than zero (0).
Attempts by a nonprivileged process to increase this value or to
set an initial value greater than zero (0) results in an error.
Specifies the user priority limit of a process or set of pro‐
cesses.
If used with the PC_GETPARMS command and the pc_cid field speci‐
fies 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 speci‐
fied processes is returned and the process ID of this process is
returned by the priocntl function. If there is more than one
process sharing the highest user priority, the one returned is
implementation-dependent.
Any time sharing process can set its own ts_upri value (or that
of another process with the same user ID) to any value less than
or equal to the process's ts_uprilim value. Attempts to set the
ts_upri above the ts_uprilim (and/or set the ts_uprilim value
below the ts_upri) value results in the ts_upri value being set
equal to the ts_uprilim value.
Note that a reserved value, TS_NOCHANGE defined in <sys/tspriocntl.h>)
can be used to set either the ts_uprilim or ts_upri value without
affecting the other. Specifying TS_NOCHANGE for the ts_upri value when
the ts_uprilim value is set below the current ts_upri value causes the
ts_upri value to be set equal to the ts_uprilim value that is 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 of the ts_uprilim is zero
(0) and the default for 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 and exec functions.
NOTES
The following notes also apply: If a process which is not running in a
scheduling class recognized by priocntl attempts to use P_CID with
P_MYID, a -1 will be returned with errno set to [EINVAL]. The priocntl
function cannot be used in multithreaded applications. Attempts to do
so result in failure.
RESTRICTIONS
Some restrictions exist when changing the class or priorities of a
process or group of processes as follows: The sys scheduling class is a
special purpose category that is used solely to manage the scheduling
priorities of special system processes such as the swapper. The class
of a process that belongs to the sys class cannot be changed (with the
exception of the init process). Attempts to change the class or prior‐
ities of a process in the sys class are ignored by the priocntl func‐
tion.
The class or scheduling properties of the init process (Process
ID 1) can be changed if it is the only process identified by the
id and idtype arguments. Although it can be placed in any
class, it is most suited in the time-sharing class. The default
configuration enables an executable real-time process to run
before other processes. Adverse system performance may occur if
you are not careful when specifying changes to real-time pro‐
cesses.
RETURN VALUE
Unless otherwise noted above, the priocntl returns a value of zero (0)
on success. Upon failure, the priocntl function returns -1 and sets
errno to indicate the error.
ERRORS
The priocntl function fails under the following conditions: The calling
process does not have the required permissions as explained above. The
argument cmd was invalid, an invalid or unconfigured class was speci‐
fied, or one of the parameters specified was invalid. The requested
time quantum is out of range. None of the specified processes exist.
All or part of the area pointed to by one of the data pointers is out‐
side the process's address space. An attempt to change the class of a
process failed because of insufficient memory. 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
Functions: exec(2), fork(2), getpriority(2), priocntlset(2), setprior‐
ity(2)
Routines: nice(3)priocntl(2)