rtprio(2)							System Calls Manual							 rtprio(2)

NAME

       rtprio - change or read real-time priority

SYNOPSIS

DESCRIPTION

       The 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  prior-
       ity,  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 privi-
       leges.  The calling process must also be a member of a privilege group allowing (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  pro-
       cesses,	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:

	      Set the process to this real-time priority.

	      Do not change the real-time priority.
				  This is used to read the process real-time priority.

	      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.

   Security Restrictions
       Some  or all of the actions associated with this system call are subject to compartmental restrictions. See compartments(5) for more infor-
       mation about compartmentalization on systems that support that feature.	Compartmental restrictions can be overridden if the  process  pos-
       sesses  the  privilege  Processes owned by the superuser may not have this privilege.  Processes owned by any user may have this privilege,
       depending on system configuration.

       Some or all of the actions associated with this system call require one or more privileges.  Processes owned by the  superuser  have  many,
       though  not  all,  privileges.  Processes owned by other users may have privilege(s), depending on system configuration.  See privileges(5)
       for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

       returns the following values:

	      The process was a real-time process.
				  The value is the process's former (before the call) real-time priority.

	      The process was not a real-time process.

	      An error occurred.  is set to indicate the error.

ERRORS

       If fails, is set to one of the following values:

	      The target process could not be accessed due to compartmental
			     restrictions.

	      prio	     is not or in the range 0 to 127.

	      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.

	      The group access list of the calling process
			     does not contain a group having capability and prio is not or with a pid of zero.

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

EXAMPLES

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

WARNINGS

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

DEPENDENCIES

       Because processes executing at real-time priorities get scheduling preference over a system process executing at a  lower  priority,  unex-
       pected  system  behavior  can  occur  after  a power failure on systems that support power-fail recovery.  For example, when (see init(1M))
       receives the powerfail signal it normally reloads programmable hardware such as terminal  multiplexers.	 If  a	higher-priority  real-time
       process	is  eligible to run after the power failure, the running of 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 and suspend itself until has finished its powerfail processing.

AUTHOR

       was developed by HP.

SEE ALSO

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

																	 rtprio(2)