HP-UX Reference (11i v1 05/09) - 2 System Calls (vol 5)

r
rtprio(2) rtprio(2)
NAME
rtprio - change or read real-time priority
SYNOPSIS
#include <sys/rtprio.h>
int rtprio(pid_t pid, int prio);
DESCRIPTION
The rtprio() system call sets or reads the real-time priority of a process.
If pid is zero, it specifies the calling process; otherwise, it specifies the process ID of a process.
If the process pid contains more than one thread or a lightweight process (that is, the process is multi-
threaded), this function shall only change the process scheduling policy and priority. Individual threads or
lightweight processes in the target process shall not have their scheduling policies and priorities modified.
Note that if the target process is multi-threaded, this process scheduling policy and priority change will
only affect a child process that is created later and inherits its parent’s scheduling policy and priority. The
priority returned is the value of the target’s old priority, though individual threads or lightweight processes
may have a different value if some other interface is used to change an individual thread or lightweight
processes priority.
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 a 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 forks (see fork(2)) and execs (see exec(2)).
prio can have the following values:
0 to 127 Set the process to this real-time priority.
RTPRIO_NOCHG Do not change the real-time priority. This is used to read the process real-time
priority.
RTPRIO_RTOFF Set the 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 prior-
ity using a pid of zero.
RETURN VALUE
rtprio() returns the following values:
0 to 127 The process was a real-time process. The value is the process’s former (before
the call) real-time priority.
RTPRIO_RTOFF The process was not a real-time process.
-1 An error occurred. errno is set to indicate the error.
ERRORS
If rtprio() fails, errno is set to one of the following values:
[EINVAL] prio is not RTPRIO_NOCHG , RTPRIO_RTOFF , or in the range 0 to 127.
[EPERM] The calling process is not a user having appropriate privileges, and neither its
real nor effective user ID match the real or saved user ID of the process
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 2−−285