rtprio(2) rtprio(2)
NAME [Toc] [Back]
rtprio - change or read real-time priority
SYNOPSIS [Toc] [Back]
#include <sys/rtprio.h>
int rtprio(pid_t pid, int prio);
DESCRIPTION [Toc] [Back]
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 realtime
processes. This priority is not degraded over time. All realtime
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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
rtprio(2) rtprio(2)
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
priority using a pid of zero.
RETURN VALUE [Toc] [Back]
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 [Toc] [Back]
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 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.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
rtprio(2) rtprio(2)
EXAMPLES [Toc] [Back]
The following call to rtprio() sets the calling process to a real-time
priority of 90:
rtprio(0, 90);
WARNINGS [Toc] [Back]
Normally, compute-bound programs should not be run at real-time
priorities, because all timesharing work on the CPU would come to a
complete halt.
DEPENDENCIES [Toc] [Back]
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 (see
init(1M)) receives the powerfail signal SIGPWR, it normally reloads
programmable hardware such as terminal multiplexers. If a higherpriority
real-time process is eligible to run after the power failure,
the 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 [Toc] [Back]
rtprio() was developed by HP.
SEE ALSO [Toc] [Back]
rtprio(1), getprivgrp(2), nice(2), plock(2).
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003 [ Back ] |
