priocntl(2) System Calls Manual priocntl(2)
NAME
priocntl - manage scheduling properties of process
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,
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
definition 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 pro-
cesses 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 param-
eter 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 processes specified by the id and idtype parameters. The arg
parameter is a pointer to a pcparms_t structure that is discussed in the next subsection. 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/tspriocntl.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 parameter. 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 spec-
ified, 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. Pro-
cesses with the same priority value share the same scheduling queue. All processes 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 sched-
uling 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
target process.
The real-time priority and time quantum are inherited
Time-Sharing Class
Processes that vary in CPU consumption, but which still require a reasonable response time with some user or application control over
scheduling 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
installation 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 priority 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
section on Include Files.
POSIX Round Robin Class
This class is the same as the real-time class when a finite time quantum is specified. The POSIX round-robin class uses the same struc-
tures 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 sched-
uling 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 spe-
cific 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 buffer 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 processes.
The rt_tqnsecs field specifies the number of additional nanoseconds 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 implementation-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 values 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 buffer specifies the time sharing class, the data in the pc_clparms buf-
fer 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 processes.
All time sharing processes can lower its own ts_uprilim value (or that of another process with the same user ID). Only a time-shar-
ing 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 processes.
If used with the PC_GETPARMS command and the pc_cid field 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 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 priorities of a process in the sys class are ignored by the priocntl function.
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 configura-
tion 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 processes.
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 specified, 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 outside 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), setpriority(2)
Routines: nice(3)
priocntl(2)