priocntl - manage scheduling properties of process
#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 );
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.
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: realtime,
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 [Toc] [Back]
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 processes
with this specific parent process ID
are targeted.
P_PGID Defines id as a process group ID. All processes
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 [Toc] [Back]
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 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 [Toc] [Back]
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 specified, 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 [Toc] [Back]
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, timesharing,
POSIX round-robin, and the POSIX fifo classes
discussed in the next sections.
Real-time Class [Toc] [Back]
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 realtime
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_GETCLINFO 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 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 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 section 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 privileges. 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 [Toc] [Back]
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 [Toc] [Back]
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 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 [Toc] [Back]
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 scheduling
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 discussed in the Include Files section.
Include Files [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 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 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-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 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 implementationdependent.
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.
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.
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 configuration enables an executable realtime
process to run before other processes.
Adverse system performance may occur if you are not
careful when specifying changes to real-time processes.
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.
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).
Functions: exec(2), fork(2), getpriority(2), priocntlset(2), setpriority(2)
Routines: nice(3)
priocntl(2)
[ Back ] |
