 |
Index for
Section 2 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
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
idtype
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.
id 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.
cmd Specifies the how the process or group of processes are affected.
arg 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
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
The five commands currently supported by the priocntl function are as
follows:
PC_GETCID
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.
PC_GETCLINFO
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).
PC_SETPARMS
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.
PC_GETPARMS
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.
PC_ADMIN
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
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
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_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
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 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 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
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 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;
rt_pri
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.
rt_tqsecs
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.
rt_tqnsecs
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:
RT_TQINF
Sets an infinite time quantum. This must be used if you have
selected the POSIX fifo class for your process or processes.
RT_TQDEF
Sets the time quantum to the default for this priority.
RT_NOCHANGE
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 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;
ts_uprilim
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.
ts_upri
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 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 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:
[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
Functions: exec(2), fork(2), getpriority(2), priocntlset(2),
setpriority(2)
Routines: nice(3)
|
Index for
Section 2 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|