priocntl(2) priocntl(2)
NAME
priocntl - process scheduler control
SYNOPSIS
#include <sys/types.h>
#include <sys/priocntl.h>
#include <sys/procset.h>
#include <sys/rtpriocntl.h>
#include <sys/tspriocntl.h>
#include <sys/fppriocntl.h>
long priocntl(idtypet idtype, idt id, int cmd, ... /* arg */);
DESCRIPTION
priocntl() provides for control over the scheduling of active
processes.
Processes fall into distinct classes with a separate scheduling policy
applied to each class. The three classes currently supported are the
real-time class, the time-sharing class and the fixed-priority class.
The characteristics of these classes are described under the corre-
sponding headings below. The class attribute of a process is inherited
across the fork(2) and exec(2) system calls. priocntl() can be used to
dynamically change the class and other scheduling parameters associ-
ated with a running process or set of processes given the appropriate
permissions as explained below.
In the default configuration, a runnable real-time process runs before
any other process. Therefore, inappropriate use of real-time processes
can have a dramatic negative impact on system performance.
priocntl() provides a interface for specifying a process or set of
processes to which the system call is to apply. The priocntlset() sys-
tem call provides the same functions as priocntl(), but allows a more
general interface for specifying the set of processes to which the
system call is to apply.
Page 1 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
For priocntl(), the idtype and id arguments are used together to
specify the set of processes. The interpretation of id depends on the
value of idtype. The possible values for idtype and corresponding
interpretations of id are as follows:
PPID id is a process ID specifying a single process to which the
priocntl() system call is to apply.
PPPID id is a parent process ID. The priocntl() system call applies
to all processes with the specified parent process ID.
PPGID id is a process group ID. The priocntl() system call applies
to all processes in the specified process group.
PSID id is a session ID. The priocntl() system call applies to all
processes in the specified session.
PCID id is a class ID (returned by priocntl() PCGETCID as
explained below). The priocntl() system call applies to all
processes in the specified class.
PUID id is a user ID. The priocntl() system call applies to all
processes with this effective user ID.
PGID id is a group ID. The priocntl() system call applies to all
processes with this effective group ID.
PALL The priocntl() system call applies to all existing processes.
The value of id is ignored. The permission restrictions
described below still apply.
An id value of PMYID can be used in conjunction with the idtype value
to specify the calling process' process ID, parent process ID, process
group ID, session ID, class ID, user ID, or group ID.
In order to change the scheduling parameters of a process (using the
PCSETPARMS command as explained below) the real or effective user ID
of the process calling priocntl() must match the real or effective
user ID of the receiving process or the effective user ID of the cal-
ling process must be superuser. These are the minimum permission
requirements enforced for all classes. An individual class may impose
additional permissions requirements when setting processes to that
class and/or when setting class-specific scheduling parameters.
A special sys scheduling class exists for the purpose of scheduling
the execution of certain special system processes (such as the swapper
process). It is not possible to change the class of any process to
sys. In addition, any processes in the sys class that are included in
a specified set of processes are disregarded by priocntl(). For exam-
ple, an idtype of PUID and an id value of zero would specify all
processes with a user ID of zero except processes in the sys class and
(if changing the parameters using PCSETPARMS) the init process.
Page 2 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
The init process is a special case. In order for a priocntl() call to
change the class or other scheduling parameters of the init process
(process ID 1), it must be the only process specified by idtype and
id. The init process may be assigned to any class configured on the
system, but the time-sharing class is almost always the appropriate
choice.
The data type and value of arg are specific to the type of command
specified by cmd.
The following structure is used by the PCGETCID and PCGETCLINFO com-
mands.
typedef struct {
idt pccid; /* Class id */
char pcclname[PCCLNMSZ]; /* Class name */
long pcclinfo[PCCLINFOSZ]; /* Class information */
} pcinfot;
pccid is a class ID returned by priocntl() PCGETCID. pcclname is a
buffer of size PCCLNMSZ (defined in sys/priocntl.h) used to hold the
class name (RT for real-time, TS for time-sharing, or FP for fixed-
priority).
pcclinfo is a buffer of size PCCLINFOSZ (defined in sys/priocntl.h)
used to return data describing the attributes of a specific class. The
format of this data is class-specific and is described below under the
appropriate heading.
The following structure is used by the PCSETPARMS and PCGETPARMS
commands.
typedef struct {
idt pccid; /* Process class */
long pcclparms[PCCLPARMSZ]; /* Class-specific params */
} pcparmst;
pccid is a class ID (returned by priocntl PCGETCID). The special
class ID PCCLNULL can also be assigned to pccid when using the
PCGETPARMS command as explained below.
The pcclparms buffer holds class-specific scheduling parameters. The
format of this parameter data for a particular class is described
under the appropriate heading below. PCCLPARMSZ is the length of the
pcclparms buffer and is defined in sys/priocntl.h.
Page 3 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
Commands
PCGETCID
Gets class ID and class attributes for a specific class with
given class name. The idtype and id arguments are ignored. If arg
is not NULL, it points to a structure of type pcinfot. The
pcclname buffer contains the name of the class whose attributes
you are getting.
On success, the class ID is returned in pccid, the class attri-
butes are returned in the pcclinfo buffer, and the priocntl()
call returns the total number of classes configured in the system
(including the sys class). If the class specified by pcclname is
invalid or is not currently configured the priocntl() call
returns -1 with errno set to EINVAL. The format of the attribute
data returned for a given class is defined in the
sys/rtpriocntl.h, sys/tspriocntl.h, or sys/fppriocntl.h header
file and described under the appropriate heading below.
If arg is a NULL pointer, no attribute data is returned but the
priocntl() call still returns the number of configured classes.
PCGETCLINFO
Gets class name and class attributes for a given class ID. The
idtype and id arguments are ignored. If arg is nonnull, it points
to a structure of type pcinfot. pccid is the class ID of the
class whose attributes you are getting.
On success, the class name is returned in the pcclname buffer,
the class attributes are returned in the pcclinfo buffer, and
the priocntl() call returns the total number of classes config-
ured in the system (including the sys class). The format of the
attribute data returned for a given class is defined in the
sys/rtpriocntl.h, sys/tspriocntl.h, or sys/fppriocntl.h header
file and described under the appropriate heading below.
If arg is a NULL pointer, no attribute data is returned but the
priocntl() call still returns the number of configured classes.
PCSETPARMS
Sets the class and class-specific scheduling parameters of the
specified process(es). arg points to a structure of type
pcparmst. pccid specifies the class you are setting and the
pcclparms buffer contains the class-specific parameters you are
setting. The format of the class-specific parameter data is
defined in the sys/rtpriocntl.h, sys/tspriocntl.h, or
sys/fppriocntl.h header file and described under the appropriate
class heading below.
Page 4 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
When setting parameters for a set of processes, priocntl() acts
on the processes in the set in an implementation-specific order.
If priocntl() encounters an error for one or more of the target
processes, it may or may not continue through the set of
processes, depending on the nature of the error. If the error is
related to permissions (EPERM), priocntl() continues through the
process set, resetting the parameters for all target processes
for which the calling process has appropriate permissions.
priocntl() then returns -1 with errno set to EPERM to indicate
that the operation failed for one or more of the target
processes. If priocntl() encounters an error other than permis-
sions, it does not continue through the set of target processes
but returns the error immediately.
PCGETPARMS
Get the class and/or class-specific scheduling parameters of a
process. arg points the a structure of type pcparmst.
If pccid specifies a configured class and a single process
belonging to that class is specified by the idtype and id values
or the procset structure, then the scheduling parameters of that
process are returned in the pcclparms buffer. If the process
specified does not exist or does not belong to the specified
class, the priocntl() call returns -1 with errno set to ESRCH.
If pccid specifies a configured class and a set of processes is
specified, the scheduling parameters of one of the specified
processes belonging to the specified class are returned in the
pcclparms buffer and the priocntl() call returns the process ID
of the selected process. The criteria for selecting a process to
return in this case is class dependent. If none of the specified
processes exist or none of them belong to the specified class the
priocntl() call returns -1 with errno set to ESRCH.
If pccid is PCCLNULL and a single process is specified the
class of the specified process is returned in pccid and its
scheduling parameters are returned in the pcclparms buffer.
PCADMIN
This command provides functionality needed for the implementation
of the dispadmin(1M) command. It is not intended for general use
by other applications.
REAL-TIME CLASS
The real-time class provides a fixed priority preemptive scheduling
policy for those processes requiring fast and deterministic response
and absolute user/application control of scheduling priorities. If the
real-time class is configured in the system it should have exclusive
control of the highest range of scheduling priorities on the system.
This ensures that a runnable real-time process is given CPU service
before any process belonging to any other class.
Page 5 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
The real-time class has a range of real-time priority (rtpri) values
that may be assigned to processes within the class. Real-time priori-
ties range from 0 to x, where the value of x is configurable and can
be determined for a specific installation by using the priocntl()
PCGETCID or PCGETCLINFO command.
The real-time scheduling policy is a fixed priority policy. The
scheduling priority of a real-time process is never changed except as
the result of an explicit request by the user/application to change
the rtpri value of the process.
For processes in the real-time class, the rtpri value is, for all
practical purposes, equivalent to the scheduling priority of the pro-
cess. The rtpri value completely determines the scheduling priority
of a real-time process relative to other processes within its class.
Numerically higher rtpri values represent higher priorities. Since
the real-time class controls the highest range of scheduling priori-
ties in the system it is guaranteed that the runnable real-time pro-
cess with the highest rtpri value is always selected to run before
any other process in the system.
In addition to providing control over priority, priocntl() provides
for control over the length of the time quantum allotted to processes
in the real-time class. The time quantum value specifies the maximum
amount of time a process may run assuming that it does not complete or
enter a resource or event wait state (sleep()). Note that if another
process becomes runnable at a higher priority the currently running
process may be preempted before receiving its full time quantum.
The system's process scheduler keeps the runnable real-time processes
on a set of scheduling queues. There is a separate queue for each con-
figured real-time priority and all real-time processes with a given
rtpri value are kept together on the appropriate queue. The processes
on a given queue are ordered in FIFO order (that is, the process at
the front of the queue has been waiting longest for service and
receives the CPU first). Real-time processes that wake up after sleep-
ing, processes which change to the real-time class from some other
class, processes which have used their full time quantum, and runnable
processes whose priority is reset by priocntl() are all placed at the
back of the appropriate queue for their priority. A process that is
preempted by a higher priority process remains at the front of the
queue (with whatever time is remaining in its time quantum) and runs
before any other process at this priority. Following a fork(2) system
call by a real-time process, the parent process continues to run while
the child process (which inherits its parent's rtpri value) is placed
at the back of the queue.
Page 6 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
The following structure (defined in sys/rtpriocntl.h) defines the for-
mat used for the attribute data for the real-time class.
typedef struct {
short rtmaxpri; /* Maximum real-time priority */
} rtinfot;
The priocntl PCGETCID and PCGETCLINFO commands return real-time
class attributes in the pcclinfo buffer in this format.
rtmaxpri specifies the configured maximum rtpri value for the real-
time class (if rtmaxpri is x, the valid real-time priorities range
from 0 to x).
The following structure (defined in sys/rtpriocntl.h) defines the for-
mat used to specify the real-time class-specific scheduling parameters
of a process.
typedef struct {
short rtpri; /* Real-Time priority */
ulong rttqsecs; /* Seconds in time quantum */
long rttqnsecs; /* Additional nanoseconds in quantum */
} rtparmst;
When using the priocntl PCSETPARMS or PCGETPARMS commands, if pccid
specifies the real-time class, the data in the pcclparms buffer is in
this format.
The above commands can be used to set the real-time priority to the
specified value or get the current rtpri value. Setting the rtpri
value of a process that is currently running or runnable (not sleep-
ing) causes the process to be placed at the back of the scheduling
queue for the specified priority. The process is placed at the back of
the appropriate queue regardless of whether the priority being set is
different from the previous rtpri value of the process. Note that a
running process can voluntarily release the CPU and go to the back of
the scheduling queue at the same priority by resetting its rtpri
value to its current real-time priority value. In order to change the
time quantum of a process without setting the priority or affecting
the process' position on the queue, the rtpri field should be set to
the special value RTNOCHANGE (defined in sys/rtpriocntl.h). Specify-
ing RTNOCHANGE when changing the class of a process to real-time from
some other class results in the real-time priority being set to zero.
For the priocntl PCGETPARMS command, if pccid specifies the real-
time class and more than one real-time process is specified, the
scheduling parameters of the real-time process with the highest rtpri
value among the specified processes are returned and the process ID of
this process is returned by the priocntl() call. If there is more than
one process sharing the highest priority, the one returned is
implementation-dependent.
Page 7 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
The rttqsecs and rttqnsecs fields are used for getting or setting
the time quantum associated with a process or group of processes.
rttqsecs is the number of seconds in the time quantum and rttqnsecs
is the number of additional nanoseconds in the quantum. For example
setting rttqsecs to 2 and rttqnsecs to 500,000,000 (decimal) would
result in a time quantum of two and one-half seconds. Specifying a
value of 1,000,000,000 or greater in the rttqnsecs field results in
an error return with errno set to EINVAL. Although the resolution of
the tqnsecs field is very fine, the specified time quantum length is
rounded up by the system to the next integral multiple of the system
clock's resolution. For example, the finest resolution currently
available on the 3B2 is 10 milliseconds (1 "tick"). Setting rttqsecs
to 0 and rttqnsecs to 34,000,000 would specify a time quantum of 34
milliseconds, which would be rounded up to 4 ticks (40 milliseconds)
on the 3B2. The maximum time quantum that can be specified is
implementation-specific and equal to LONGMAX ticks (defined in
limits.h). Requesting a quantum greater than this maximum results in
an error return with errno set to ERANGE (although infinite quantums
may be requested using a special value as explained below). Requesting
a time quantum of zero (setting both rttqsecs and rttqnsecs to 0)
results in an error return with errno set to EINVAL.
The rttqnsecs field can also be set to one of the following special
values (defined in sys/rtpriocntl.h), in which case the value of
rttqsecs is ignored.
RTTQINF
Sets an infinite time quantum.
RTTQDEF
Sets the time quantum to the default for this priority [see
rtdptbl(4)].
RTNOCHANGE
Don't set the time quantum. This value is useful when you wish to
change the real-time priority of a process without affecting the
time quantum. Specifying this value when changing the class of a
process to real-time from some other class is equivalent to
specifying RTTQDEF.
In order to change the class of a process to real-time (from any other
class) the process invoking priocntl() must have superuser privileges.
In order to change the priority or time quantum setting of a real-time
process the process invoking priocntl() 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 across the
fork(2) and exec(2) system calls.
Page 8 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
TIME-SHARING CLASS
The time-sharing scheduling policy provides for a fair and effective
allocation of the CPU resource among processes with varying CPU con-
sumption characteristics. The objectives of the time-sharing policy
are to provide good response time to interactive processes and good
throughput to CPU-bound jobs while providing a degree of
user/application control over scheduling.
The time-sharing class has a range of time-sharing user priority (see
tsupri below) values that may be assigned to processes within the
class. A tsupri value of zero is defined as the default base priority
for the time-sharing class. User priorities range from -x to +x where
the value of x is configurable and can be determined for a specific
installation by using the priocntl PCGETCID or PCGETCLINFO command.
The purpose of the user priority is to provide some degree of
user/application control over the scheduling of processes in the
timesharing class. Raising or lowering the tsupri value of a process
in the time-sharing class raises or lowers the scheduling priority of
the process. It is not guaranteed, however, that a process with a
higher tsupri value will run before one with a lower tsupri value.
This is because the tsupri value is just one factor used to determine
the scheduling priority of a time-sharing process. The system may
dynamically adjust the internal scheduling priority of a time-sharing
process based on other factors such as recent CPU usage.
In addition to the system-wide limits on user priority (returned by
the PCGETCID and PCGETCLINFO commands) there is a per process user
priority limit (see tsuprilim below), which specifies the maximum
tsupri value that may be set for a given process; by default,
tsuprilim is zero.
The following structure (defined in sys/tspriocntl.h) defines the for-
mat used for the attribute data for the time-sharing class.
typedef struct {
short tsmaxupri; /* Limits of user priority range */
} tsinfot;
The priocntl PCGETCID and PCGETCLINFO commands return timesharing
class attributes in the pcclinfo buffer in this format.
tsmaxupri specifies the configured maximum user priority value for
the time-sharing class. If tsmaxupri is x, the valid range for both
user priorities and user priority limits is from -x to +x.
The following structure (defined in sys/tspriocntl.h) defines the for-
mat used to specify the time-sharing class-specific scheduling parame-
ters of a process.
Page 9 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
typedef struct {
short tsuprilim; /* Time-Sharing user priority limit */
short tsupri; /* Time-Sharing user priority */
short tsflags; /* (see below) */
} tsparmst;
/* tsparmst.tsflags values */
#define TSFIXEDPRI 1
When using the priocntl PCSETPARMS or PCGETPARMS commands, if pccid
specifies the time-sharing class, the data in the pcclparms buffer is
in this format.
For the priocntl PCGETPARMS command, if pccid specifies the time-
sharing class and more than one time-sharing process is specified, the
scheduling parameters of the time-sharing process with the highest
tsupri value among the specified processes is returned and the pro-
cess ID of this process is returned by the priocntl() call. If there
is more than one process sharing the highest user priority, the one
returned is implementation-dependent.
Any time-sharing process may lower its own tsuprilim (or that of
another process with the same user ID). Only a time-sharing process
with superuser privileges may raise a tsuprilim. When changing the
class of a process to time-sharing from some other class, superuser
privileges are required in order to set the initial tsuprilim to a
value greater than zero. Attempts by a non-superuser process to raise
a tsuprilim or set an initial tsuprilim greater than zero fail with
a result of -1 and errno set to EPERM.
Any time-sharing process may set its own tsupri (or that of another
process with the same user ID) to any value less than or equal to the
process' tsuprilim. Attempts to set the tsupri above the tsuprilim
(and/or set the tsuprilim below the tsupri) result in the tsupri
being set equal to the tsuprilim.
The tsparmst structure also has a tsflags value that can be set by a
process with super-user privileges. If the flag has the TSFIXEDPRI
flag bit set, then the time-share scheduling class will not degrade
the priority of the process when it consumes its entire time slice.
This feature is useful for processes such as system daemons and data-
base servers. This feature has been replaced by the fixed-priority
class. It is left only for compatibility purposes and will be removed
in a future release.
Any of the tsuprilim, tsupri, or tsflags fields may be special
value TSNOCHANGE (defined in sys/tspriocntl.h) in order to set one of
the values without affecting the other. Specifying TSNOCHANGE for the
tsupri when the tsuprilim is being set to a value below the current
tsupri causes the tsupri to be set equal to the tsuprilim being
set. Specifying TSNOCHANGE for a parameter when changing the class of
a process to time-sharing (from some other class) causes the parameter
Page 10 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
to be set to a default value. The default value for the tsuprilim is
0 and the default for the tsupri is to set it equal to the tsuprilim
which is being set.
The time-sharing user priority and user priority limit are inherited
across the fork(2) and exec(2) system calls.
FIXED-PRIORITY CLASS
The fixed-priority class provides a fixed priority preemptive schedul-
ing policy for those processes requiring fast and deterministic
response and absolute user/application control of scheduling priori-
ties much like the real-time class. However, the fixed-priority class
has scheduling priorities that extend only slightly higher than the
time-share class. This allows a process to get a great deal of the CPU
without preventing the kernel from running.
The fixed-priority class has a range of fixed-priority priority
(fpumdpri) values that may be assigned to processes within the class.
Fixed-priority priorities range from 0 to x, where the value of x is
configurable and can be determined for a specific installation by
using the priocntl PCGETCID or PCGETCLINFO command.
The fixed-priority scheduling policy is a fixed priority policy. The
scheduling priority of a fixed-priority process is only changed when
the process goes to sleep in the kernel, or as the result of an expli-
cit request by the user/application to change the fpumdpri value of
the process.
The fpumdpri value is (for processes in the fixed-priority class) the
scheduling priority of the process. The fpumdpri value completely
determines the scheduling priority of a fixed-priority process rela-
tive to other processes. Numerically higher fpumdpri values represent
higher priorities.
In addition to providing control over priority, priocntl provides for
control over the length of the time quantum allotted to processes in
the fixed-priority class. The time quantum value specifies the maximum
amount of time a process may run assuming that it does not complete or
enter a resource or event wait state (sleep). If another process
becomes runnable at a higher priority the currently running process
may be preempted before receiving its full time quantum.
The system's process scheduler keeps the runnable fixed-priority
processes on a set of scheduling queues. There is a separate queue for
each configured fixed-priority priority and all fixed-priority
processes with a given fpumdpri value are kept together on the
appropriate queue. The processes on a given queue are ordered in FIFO
order (that is, the process at the front of the queue has been waiting
longest for service and receives the CPU first).
Page 11 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
Fixed-priority processes that wake up after sleeping, processes which
change to the fixed-priority class from some other class, processes
which have used their full time quantum, and runnable processes whose
priority is reset by priocntl are all placed at the back of the
appropriate queue for their priority.
A process that is preempted by a higher priority process gets placed
in the queue according to whatever time is remaining in its time quan-
tum. Following a fork(2) system call by a fixed-priority process, the
parent process relinquishes the CPU to the child process and is placed
on the back of its scheduler priority queue.
The following structure (defined in <sys/fppriocntl.h>) defines the
format used for the attribute data for the fixed-priority class.
typedef struct {
short fpmaxumdpri; /* configured limits of user priority range */
} fpinfot;
The priocntl PCGETCID and PCGETCLINFO commands return fixed-priority
class attributes in the pcclinfo buffer in this format.
fpmaxumdpri specifies the configured maximum fpumdpri value for the
fixed-priority class (if rtmaxumdpri is x, the valid fixed-priority
priorities range from 0 to x).
The following structure (defined in <sys/fppriocntl.h>) defines the
format used to specify the fixed-priority class-specific scheduling
parameters of a process.
typedef struct {
short fppri; /* Real-Time priority */
ulong fptqsecs; /* Seconds in time quantum */
long fptqnsecs; /* Additional nanoseconds in quantum */
} fpparmst;
When using the priocntl PCSETPARMS or PCGETPARMS commands, if pccid
specifies the fixed-priority class, the data in the pcclparms buffer
is in this format.
These commands can be used to set the fixed-priority priority to the
specified value or get the current fppri value. Setting the fppri
value of a process that is currently running or runnable (not sleep-
ing) causes the process to be placed at the back of the scheduling
queue for the specified priority. The process is placed at the back of
the appropriate queue regardless of whether the priority being set is
different from the previous fppri value of the process.
A running process can voluntarily release the CPU and go to the back
of the scheduling queue at the same priority by resetting its fppri
value to its current fixed-priority priority value.
Page 12 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
For the priocntl PCGETPARMS command, if pccid specifies the fixed-
priority class and more than one fixed-priority process is specified,
the scheduling parameters of the fixed-priority process with the
highest fpumdpri value among the specified processes are returned and
the process ID of this process is returned by the priocntl call. If
there is more than one process sharing the highest priority, the one
returned is implementation-dependent.
The fptqsecs and fptqnsecs fields are used for getting or setting
the time quantum associated with a process or group of processes.
fptqsecs is the number of seconds in the time quantum and fptqnsecs
is the number of additional nanoseconds in the quantum. For example
setting fptqsecs to 2 and fptqnsecs to 500,000,000 (decimal) would
result in a time quantum of two and one-half seconds. Specifying a
value of 1,000,000,000 or greater in the fptqnsecs field results in
an error return with errno set to EINVAL. Although the resolution of
the tqnsecs field is very fine, the specified time quantum length is
rounded up by the system to the next integral multiple of the system
clock's resolution. For example, the finest resolution currently
available on the 3B2 is 10 milliseconds (1 "tick"). Setting fptqsecs
to 0 and fptqnsecs to 34,000,000 would specify a time quantum of 34
milliseconds, which would be rounded up to 4 ticks (40 milliseconds)
on the 3B2. The maximum time quantum that can be specified is
implementation-specific and equal to LONGMAX ticks (defined in
limits.h). Requesting a quantum greater than this maximum results in
an error return with errno set to ERANGE (although infinite quantums
may be requested using a special value as explained below). Requesting
a time quantum of zero (setting both fptqsecs and fptqnsecs to 0)
results in an error return with errno set to EINVAL.
The fptqnsecs field can also be set to one of the following special
values (defined in sys/rtpriocntl.h), in which case the value of
fptqsecs is ignored.
FPTQINF
Sets an infinite time quantum.
FPTQDEF
Sets the time quantum to the default for this priority [see
fpdptbl(4)].
FPNOCHANGE
Don't set the time quantum. This value is useful when you wish to
change the real-time priority of a process without affecting the
time quantum. Specifying this value when changing the class of a
process to real-time from some other class is equivalent to
specifying FPTQDEF.
Page 13 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
In order to change the class of a process to fixed-priority (from any
other class) the process invoking priocntl() must have super-user
privileges. In order to change the priority setting of a fixed-
priority process the process invoking priocntl() must have super-user
privileges or must itself be a fixed-priority process whose real or
effective user ID matches the real of effective user ID of the target
process.
The fixed-priority priority is inherited across the fork(2) and
exec(2) system calls.
PROCESSOR AFFINITY AND BINDING CONSIDERATIONS
In order to increase the cache hit rates of a multiprocessor, a pro-
cess should generally execute on a particular processor. This affinity
for a particular processor will reduce the required memory bandwidth
for the process (and for the system as a whole). If a process has not
run recently then it probably only has a small cache state in any
given processor and therefore, should loose its affinity for any par-
ticular processor.
This affinity mechanism can be enabled or disabled on a per-process
basis by the super user. See mpcntl(3X). The affinity mechanism
defaults to on for the TS and FP classes and to off for the RT class.
A process can also be bound to a set of processors. If a processor has
been so bound, then it will only run on one of the processors of that
set. If there is a idle processor that is not in the processes binding
set - then the process will still wait until there is a processor in
its set that is not running a higher priority process.
Process bindings can be established by the process or can be tem-
porarily established by the kernel (if the kernel is executing driver
code that must run on a particular CPU). See mpcntl(3X).
RETURN VALUE
Unless otherwise noted, priocntl returns a value of 0 on success.
priocntl returns -1 on failure and sets errno to indicate the error.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
priocntl() fails if one or more of the following are true:
EPERM The calling process does not have the required permissions
as explained above.
EINVAL The argument cmd was invalid, an invalid or unconfigured
class was specified, or one of the parameters specified was
invalid.
EDOM The requested time quantum is out of range.
Page 14 Reliant UNIX 5.44 Printed 11/98
priocntl(2) priocntl(2)
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' 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
priocntl(1), dispadmin(1M), exec(2), fork(2), nice(2), priocntlset(2),
mpcntl(3X), fpdptbl(4), rtdptbl(4), tsdptbl(4), types(5).
Page 15 Reliant UNIX 5.44 Printed 11/98