NAME

rtprio − change or read real-time priority

SYNOPSIS

#include <sys/rtprio.h>

int rtprio(pid_t pid, int prio);

DESCRIPTION

rtprio() is used to set or read the real-time priority of a process.  If pid is zero, it names the calling process; otherwise it gives the pid of the process.  When setting the real-time priority of another process, the real or effective user ID of the calling process must match the real or saved user ID of the process to be modified, or the effective user ID of the calling process must be that of a user having appropriate privileges.  The calling process must also be a member of a privilege group allowing rtprio() (see getprivgrp(2)) or the effective user ID of the calling process must be a user having appropriate privileges.  Simply reading real-time priorities requires no special privilege. 

Real-time scheduling policies differ from normal timesharing policies in that the real-time priority is used to absolutely order all real-time processes; this priority is not degraded over time.  All real-time processes are of higher priority than normal user and system processes, although some system processes may run at real-time priorities.  If there are several eligible processes at the same priority level, they are run in a round robin fashion as long as no process with higher priority intervenes.  A real-time process receives CPU service until it either voluntarily gives up the CPU or is preempted by a process of equal or higher priority.  Interrupts can also preempt a real-time process. 

Valid real-time priorities run from zero to 127.  Zero is the highest (most important) priority.  This real-time priority is inherited across fork()s and exec()s. 

prio specifies the following:

0−127 Set process to this real-time priority. 

RTPRIO_NOCHG Do not change real-time priority.  This is used for reading the process real-time priority. 

RTPRIO_RTOFF Set this process to no longer have a real-time priority.  It resumes a normal timesharing priority.  Any process, regardless of privilege, is allowed to turn off its own real-time priority using a pid of zero. 

EXAMPLES

The following call to rtprio() sets the calling process to a real-time priority of 90:

rtprio (0, 90);

RETURN VALUE

If no error occurs, rtprio() returns the pid’s former (before the call) real-time priority. If the process was not a real-time process, RTPRIO_RTOFF is returned.  If an error occurs, rtprio() returns −1 and sets errno to indicate the error. 

ERRORS

rtprio() fails if any of the following conditions are encountered:

[EINVAL] prio is not RTPRIO_NOCHG, RTPRIO_RTOFF, or in the range of 0 through 127. 

[EPERM] The calling process is not a user having appropriate privileges, and neither its real or effective user-id match the real or saved user ID of the process indicated by pid.

[EPERM] The group access list of the calling process does not contain a group having PRIV_RTPRIO capability and prio is not RTPRIO_NOCHG, or RTPRIO_RTOFF with a pid of zero. 

[ESRCH] No process can be found corresponding to that specified by pid. 

DEPENDENCIES

Series 800:

Because processes executing at real-time priorities get scheduling preference over a system process executing at a lower priority, unexpected system behavior can occur after a power failure on systems that support power-fail recovery.  For example, when init(1M) receives the powerfail signal SIGPWR, it normally reloads programmable hardware such as terminal multiplexers.  If a higher-priority real-time process is eligible to run after the power failure, running of init is delayed.  This condition temporarily prevents terminal input to any process, including real-time shells of higher priority than the eligible real-time process.  To avoid this situation, a real-time process should catch SIGPWR and suspend itself until init has finished its powerfail processing. 

AUTHOR

rtprio() was developed by HP. 

SEE ALSO

rtprio(1), getprivgrp(2), nice(2), plock(2), privilege(5). 

WARNINGS

Normally, compute-bound programs should not be run at real-time priorities, because all time sharing work on the CPU would come to a complete halt. 

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992