priocntl -d [-i idtype] [idlist]

priocntl -s [-c class] [class-specific options] \
     [-i idtype] [idlist]

priocntl -e [-c class] [class-specific options] command \
     [argument...]

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.

The real-time class has a range of real-time priority (rtpri) values that may be assigned to processes within the class. Real-time priorities range from 0 to x, where the value of x is configurable and can be displayed for a specific installation that has already configured a real-time scheduler, by using the command

priocntl -l

The real-time scheduling policy is a fixed priority policy. The scheduling priority of a real-time process never changes 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 process. 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 priorities in the system, it is guaranteed that the runnable real-time process 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). Notice that if another process becomes runnable at a higher priority, the currently running process may be preempted before receiving its full time quantum.

The command

priocntl -d [-i idtype] [idlist]

displays the real-time priority, time quantum (in millisecond resolution), and time quantum signal value for each real-time process in the set specified by idtype and idlist.

Any combination of the -p, -t [-r], and -q options may be used with priocntl -s or priocntl -e for the real-time class. If an option is omitted and the process is currently real-time, the associated parameter is unaffected. If an option is omitted when changing the class of a process to real-time from some other class, the associated parameter is set to a default value. The default value for rtpri is 0 and the default for time quantum is dependent on the value of rtpri and on the system configuration; see rt_dptbl(4).

When using the -t tqntm option, you may optionally specify a resolution using the -r res option. (If no resolution is specified, millisecond resolution is assumed.) If res is specified, it must be a positive integer between 1 and 1,000,000,000 inclusively and the resolution used is the reciprocal of res in seconds. For example, specifying -t 10 -r 100 would set the resolution to hundredths of a second and the resulting time quantum length would be 10/100 seconds (one tenth of a second). Although very fine (nanosecond) resolution may be specified, the time quantum length is rounded up by the system to the next integral multiple of the system clock's resolution. Requests for time quantums of zero or quantums greater than the (typically very large) implementation-specific maximum quantum result in an error.

The real-time time quantum signal can be used to notify runaway real-time processes about the consumption of their time quantum. Those processes, which are monitored by the real-time time quantum signal, receive the configured signal in the event of time quantum expiration. The default value (0) of the time quantum signal tqsig will denote no signal delivery. A positive value will denote the delivery of the signal specified by the value. Like kill(1) and other commands operating on signals, the -q tqsig option is also able to handle symbolically named signals, like XCPU or KILL.

In order to change the class of a process to real-time (from any other class), the user invoking priocntl must have super-user privilege. In order to change the rtpri value or time quantum of a real-time process, the user invoking priocntl must either be super-user, or must currently be in the real-time class (shell running as a real-time process) with a real or effective user ID matching the real or effective user ID of the target process.

The real-time priority, time quantum, and time quantum signal are inherited across the fork(2) and exec(2) system calls. When using the time quantum signal with a user defined signal handler across the exec(2) system call, the new image must install an appropriate user defined signal handler before the time quantum expires. Otherwise, unpredicable behavior would result.

The time-sharing scheduling policy provides for a fair and effective allocation of the CPU resource among processes with varying CPU consumption 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 (tsupri) values that may be assigned to processes within the class. User priorities range from -x to +x, where the value of x is configurable. The range for a specific installation can be displayed by using the command

priocntl -l

The purpose of the user priority is to provide some degree of user/application control over the scheduling of processes in the time-sharing 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 time-sharing 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 (displayed with priocntl -l), there is a per process user priority limit (tsuprilim), which specifies the maximum tsupri value that may be set for a given process.

The command

priocntl -d [-i idtype] [idlist]

displays the user priority and user priority limit for each time-sharing process in the set specified by idtype and idlist.

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 super-user privilege may raise a tsuprilim. When changing the class of a process to time-sharing from some other class, super-user privilege is required in order to set the initial tsuprilim to a value greater than zero.

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's 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.

Any combination of the -m and -p options may be used with priocntl -s or priocntl -e for the time-sharing class. If an option is omitted and the process is currently time-sharing, the associated parameter is normally unaffected. The exception is when the -p option is omitted and -m is used to set a tsuprilim below the current tsupri. In this case, the tsupri is set equal to the tsuprilim which is being set. If an option is omitted when changing the class of a process to time-sharing from some other class, the associated parameter is set to a default value. The default value for tsuprilim is 0 and the default for tsupri is to set it equal to the tsuprilim value which is being set.

The time-sharing user priority and user priority limit are inherited across the fork(2) and exec(2) system calls.

The inter-active scheduling policy provides for a fair and effective allocation of the CPU resource among processes with varying CPU consumption characteristics while providing good responsiveness for user interaction. The objectives of the inter-active policy are to provide good response time to interactive processes and good throughput to CPU-bound jobs. The priorities of processes in the inter-active class can be changed in the same manner as those in the time-sharing class, though the modified priorities will continue to be adjusted to provide good responsiveness for user interaction.

The inter-active user priority limit, iaupri, is equivalent to tsupri. The inter-active per process user priority, iauprilim, is equivalent to tsuprilim.

Inter-active class processes that have the iamode ("interactive mode") bit set are given a priority boost value of 10, which is factored into the user mode priority of the process when that calculation is made, that is, every time a process's priority is adjusted. This feature is used by the X windowing system, which sets this bit for those processes that run inside of the current active window to give them a higher priority.

The fair-share scheduling policy provides a fair allocation of system CPU resources among projects, independent of the number of processes they own. Projects are given "shares" to control their entitlement to CPU resources. Resource usage is remembered over time, so that entitlement is reduced for heavy usage, and increased for light usage, with respect to other projects. CPU time is scheduled among processes according to their owner's entitlements, independent of the number of processes each project owns.

The FSS scheduling class supports the notion of per-process user priority and user priority limit for compatibility with the time-share scheduler. The fair share scheduler attempts to provide an evenly graded effect across the whole range of user priorities. Processes with positive fssupri values receive time slices less frequently than normal, while negative nice processes receive time slices more frequently than normal. Notice that user priorities do not interfere with shares. That is, changing a fssupri value of a process is not going to affect its project's overall CPU usage which only relates to the amount of shares it is allocated compared to other projects.

The priorities of processes in the fair-share class can be changed in the same manner as those in the time-share class.

The fixed-priority class provides a fixed priority preemptive scheduling policy for those processes requiring that the scheduling priorities do not get dynamically adjusted by the system and that the user/application have control of the scheduling priorities.

The fixed-priority class shares the same range of scheduling priorities with the time-sharing class, by default. The fixed-priority class has a range of fixed-priority user priority (fxupri) values that may be assigned to processes within the class. User priorities range from 0 to x, where the value of x is configurable. The range for a specific installation can be displayed by using the command

priocntl -l

The purpose of the user priority is to provide user/application control over the scheduling of processes in the fixed-priority class. For processes in the fixed-priority class, the fxupri value is, for all practical purposes, equivalent to the scheduling priority of the process. The fxupri value completely determines the scheduling priority of a fixed-priority process relative to other processes within its class. Numerically higher fxupri values represent higher priorities.

In addition to the system-wide limits on user priority (displayed with priocntl -l), there is a per process user priority limit (fxuprilim), which specifies the maximum fxupri value that may be set for a given process.

Any fixed-priority process may lower its own fxuprilim (or that of another process with the same user ID). Only a process with super-user privilege may raise a fxuprilim. When changing the class of a process to fixed-priority from some other class, super-user privilege is required in order to set the initial fxuprilim to a value greater than zero.

Any fixed-priority process may set its own fxupri (or that of another process with the same user ID) to any value less than or equal to the process's fxuprilim. Attempts to set the fxupri above the fxuprilim (and/or set the fxuprilim below the fxupri) result in the fxupri being set equal to the fxuprilim.

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, before surrendering the CPU, assuming that it does not complete or enter a resource or event wait state (sleep). Notice that if another process becomes runnable at a higher priority, the currently running process may be preempted before receiving its full time quantum.

Any combination of the -m, -p, and -t options may be used with priocntl -s or priocntl -e for the fixed-priority class. If an option is omitted and the process is currently fixed-priority, the associated parameter is normally unaffected. The exception is when the -p option is omitted and the -m option is used to set a fxuprilim below the current fxupri. In this case, the fxupri is set equal to the fxuprilim which is being set. If an option is omitted when changing the class of a process to fixed-priority from some other class, the associated parameter is set to a default value. The default value for fxuprilim is 0. The default for fxupri is to set it equal to the fxuprilim value which is being set. The default for time quantum is dependent on the fxupri and on the system configuration. See fx_dptbl( 4).

The time quantum of processes in the fixed-priority class can be changed in the same manner as those in the real-time class.

The fixed-priority user priority, user priority limit, and time quantum are inherited across the fork(2) and exec(2) system calls.

This example sets the class of any non-real-time processes selected by idtype and idlist to real-time and sets their real-time priority to the default value of 0. The real-time priorities of any processes currently in the real-time class are unaffected. The time quantums of all of the specified processes are set to 1/10 seconds.

example% priocntl -s -c RT -t 1 -r 10 -i idtype idlist

This example executes command in the real-time class with a real-time priority of 15 and a time quantum of 20 milliseconds:

example% priocntl -e -c RT -p 15 -t 20 command

This example executes command in the real-time class with a real-time priority of 11, a time quantum of 250 milliseconds, and where the specified real-time quantum signal is SIGXCPU:

example% priocntl -e -c RT -p 11 -t 250 -q XCPU command

This example sets the class of any non-time-sharing processes selected by idtype and idlist to time-sharing and sets both their user priority limit and user priority to 0. Processes already in the time-sharing class are unaffected.

example% priocntl -s -c TS -i idtype idlist

This example executes command with the arguments arguments in the time-sharing class with a user priority limit of 0 and a user priority of -15:

example% priocntl -e -c TS -m 0 -p -15 command [arguments]

This example executes a command in the fixed-priority class with a user priority limit of 20 and user priority of 10 and time quantum of 250 milliseconds:

example% priocntl -e -c FX -m 20 -p 10 -t 250 command