Content-type: text/html Man page of priocntl

priocntl

Section: System Calls (2)
Index Return to Main Contents
 

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:


idtypeid

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: 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

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;

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 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 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: 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)


 

Index

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
Process Selection
Command Descriptions
Command Arguments
Scheduling and Priority Classes
Real-time Class
Time-Sharing Class
POSIX Round Robin Class
POSIX Fifo Class
Include Files
The rtpriocntl.h Header File
Setup of Structures in tspriocntl.h
NOTES
RESTRICTIONS
RETURN VALUE
ERRORS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:40:15 GMT, October 02, 2010