rtsched(2) System Calls Manual rtsched(2)
NAME
rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_set-
param(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() - real-time scheduling operations
SYNOPSIS
DESCRIPTION
Summary
Get maximum scheduling policy
Get minimum scheduling policy
Get scheduling parameters of process
Get scheduling policy of process
Get execution time limit for a process
Set scheduling parameters of process
Set scheduling policy and parameters of process
Requeue current thread in thread list
Convert HP-UX priority to POSIX
Convert POSIX priority to HP-UX
sched_setparam()
The function sets the scheduling parameters of the process specified by pid to the values specified by the sched_param structure pointed to
by param. The value of the sched_priority member in the param structure is any integer within the inclusive priority range for the current
scheduling policy of the process specified by pid.
Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the and scheduling poli-
cies, where higher numerical values represent lower (weaker) priorities. See the and functions, and and in below.
If a process described by pid exists and if the calling process has permission, the scheduling parameters are set for the process whose
process ID is equal to pid.
If pid is zero, the scheduling parameters are set for the calling process.
If the process pid contains more than one thread or lightweight process (that is, the process is multithreaded), this function will affect
the policy and priority of individual kernel schedulable entities in the process depending on their scheduling contention scope.
o For threads created with system contention scope, this system call will have no effect on their scheduling or the scheduling of the
underlying kernel scheduled entities.
o For threads with process contention scope, the threads' scheduling parameters will not be affected. However, the underlying kernel
scheduled entities for the process contention scope threads will have their scheduling parameters changed to the value specified in
param. Kernel scheduled entities for use by process contention scope threads that are created after this call completes, inherit
their scheduling policy and associated scheduling parameters from the process.
o For single threaded processes, the scheduling parameters of its thread are also changed.
The priority returned is the old priority of the target process, 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.
Only a user with the privilege may change the scheduling parameters of another process.
The calling process must have the privilege to successfully call
The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater pri-
ority have been scheduled to run.
If the priority of any kernel schedulable entities (threads) in the process is changed and is set higher than that of the lowest priority
running thread, and if any of the modified threads is ready to run, then it will preempt the lower-priority running thread. Similarly, if
the process calling sets its own priority lower than that of one or more other nonempty thread lists, then the thread that is the head of
the highest priority list will also preempt the calling thread. Thus, in either case, the originating process may not receive notification
of the completion of the requested priority change until the higher priority thread has executed.
sched_getparam()
The function returns the scheduling parameters of a process specified by pid in the sched_param structure pointed to by param.
If a process described by pid exists, the scheduling parameters are returned for the process whose process ID is equal to pid.
If the process pid contains more than one thread or lightweight process (that is, the process is multithreaded), this function shall only
return the process scheduling policy and priority. Individual threads or lightweight processes in the target process will have their own
scheduling policies and priorities which may be different from the scheduling policy and priority of their process.
If pid is zero, the scheduling parameters are returned for the calling process.
sched_setscheduler()
The function sets the scheduling policy and scheduling parameters of the process specified by pid to policy and the parameters specified in
the sched_param structure pointed to by param, respectively. The value of the sched_priority member in the param structure can be any
integer within the inclusive priority range for the scheduling policy specified by policy.
The possible values for the policy parameter are defined in the header file and mentioned below.
If a process described by pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to
pid.
If pid is zero, the scheduling policy and scheduling parameters are set for the calling process.
If the process pid contains more than one thread or lightweight process (that is, the process is multithreaded), this function will affect
the policy and priority of individual kernel schedulable entities in the process depending on their scheduling contention scope.
o For threads created with system contention scope, this system call will have no effect on their scheduling or the scheduling of the
underlying kernel scheduled entities.
o For threads with process contention scope, the threads' scheduling parameters will not be affected. However, the underlying kernel
scheduled entities for the process contention scope threads will have their scheduling parameters changed to the value specified in
param. Kernel scheduled entities for use by process contention scope threads that are created after this call completes, inherit
their scheduling policy and associated scheduling parameters from the process.
The priority returned is the old priority of the target process, though an individual thread or lightweight process may have a different
value if some other interface is used to change individual thread's or lightweight process's priority.
The privilege is required to change the scheduling parameters of another process.
The calling process must have the privilege to successfully call
The function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by
pid to the values specified by policy and the structure param, respectively.
sched_getscheduler()
The function returns the scheduling policy of the process specified by pid.
The values that can be returned by are defined in the header file (see
If a process described by pid exists, the scheduling policy is returned for the process whose process ID is equal to pid.
If pid is zero, the scheduling policy is returned for the calling process.
If the process pid contains more than one thread or lightweight process (that is, the process is multithreaded), this function shall only
return the process scheduling policy and priority. Individual threads or lightweight processes in the target process will have their own
scheduling policies and priorities which may be different from the scheduling policy and priority of their process.
sched_yield()
The function forces the calling thread to relinquish the processor until it again becomes the head of its thread list. It takes no argu-
ments.
sched_get_priority_max(), sched_get_priority_min()
The and functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by policy.
The value of policy must be one of the scheduling policy values defined in
sched_rr_get_interval()
The function updates the timespec structure referenced by the interval argument to contain the current execution time limit (that is, time
quantum) for the process indicated by pid under the policy, at which a scheduling decision will be made when another process at the same
priority is ready to execute. If pid is zero, the current execution time limit for the calling process is returned.
PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX()
These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary
because the POSIX.4 standard chose larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be main-
tained for backward compatibility, uses smaller numbers for stronger priorities.
The function returns the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument pri. The value of pri can
be any integer.
The function returns an HP-UX process priority corresponding to the priority passed in the argument pri. The value of pri can be any inte-
ger. The HP-UX priority returned is comparable to the values returned by (see getpriority(2)).
Scheduling Policies
The scheduling policies described are defined in terms of a conceptual model, which contains a set of thread lists. There is, conceptu-
ally, one thread list for each priority. Any runnable thread may be in any thread list. Multiple scheduling policies are provided. Each
nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to
define the allowable operations on this set of lists (for example, moving threads between and within lists).
Each thread will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application
execution of the or functions. (However, these functions change scheduling parameters at process level for multithreaded processes).
Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of
other policies.
When a thread is to be selected to run, the thread that is at the head of the highest priority nonempty thread list is chosen. It is then
removed from its thread list.
The following scheduling policies are defined:
First in-first out (FIFO) scheduling policy.
Threads scheduled under this policy are chosen from a thread list that is ordered by the time its threads have been in
the list without being executed. Generally, the head of the list is the thread that has been in the list the longest
time, and the tail is the thread that has been in the list the shortest time.
Under the policy, the modification of the definitional thread lists is as follows:
o When a running thread becomes a preempted thread, it becomes the head of the thread list for its priority.
o When a blocked thread becomes a runnable thread, it becomes the tail of the thread list for its priority.
o When a running thread calls the function, the process specified in the function call is modified to the policy and
priority specified by the param argument. If the thread of a process whose policy and priority have been modified
is running or is runnable, it then becomes the tail of the thread list for its new priority.
o When a running thread calls the function, the priority of the process specified in the function call is modified
to the priority specified by the param argument. If the thread of a process whose priority has been modified is
running or is runnable, it then becomes the tail of the thread list for its new priority.
o When a running thread issues the function, the thread becomes the tail of the thread list for its priority.
o At no other time is the position of a thread with this scheduling policy within the thread lists affected.
For this policy, valid priorities are within the range returned by the functions and when is provided as the parameter.
The priority range for this policy contains at least 32 priorities.
Round-robin scheduling policy, with a per-system time slice (time quantum).
This policy is identical to the policy with the additional condition that when the implementation detects that a run-
ning thread has been executing as a running thread for a time period of length returned by the function or longer, the
thread becomes the tail of its thread list, and the head of that thread list is removed and made a running thread.
The effect of this policy is to ensure that if there are multiple threads at the same priority, one of them will not
monopolize the processor. An application should not rely only on the use of to ensure application progress among mul-
tiple processes if the application includes processes using the policy at the same or higher priority levels, or pro-
cesses at a higher priority level.
A thread under this policy that is preempted and subsequently resumes execution as a running thread completes the unex-
pired portion of its round-robin interval time period.
For this policy, valid priorities are within the range returned by the functions and when is provided as the parameter.
The priority range for this policy contains at least 32 priorities.
Round-robin scheduling policy, with a per-priority time slice (time quantum).
This policy is identical to the policy, except that the round-robin time slice interval returned by depends upon the
priority of the specified process.
For this policy, valid priorities are within the range returned by the functions and when is provided as the parameter.
The priority range for this policy contains at least 32 priorities.
Real-time scheduling policy with nondecaying priorities (like
and with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see rtprio(2)).
For processes executing under this policy, the implementation must use only priorities within the range returned by the
functions and when is provided as the parameter. Note that, for the scheduling policy, smaller numbers represent
higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continu-
ing support for existing applications that depend on this priority ordering. However, it is guaranteed that the prior-
ity range for the scheduling policy is properly disjoint from the priority ranges of all of the other scheduling poli-
cies described and the strongest priority in the priority range for is weaker than the weakest priority in the priority
ranges for any of the POSIX policies, and
Another scheduling policy.
The policy, also known as and provides a way for applications to indicate, in a portable way, that they no longer need
a real-time scheduling policy.
For processes executing under this policy, the implementation can use only priorities within the range returned by the
functions and when is provided as the parameter. Note that for the scheduling policy, like smaller numbers represent
higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continu-
ing support for existing applications that depend on this priority ordering. However, it is guaranteed that the prior-
ity range for the scheduling policy is properly disjoint from the priority ranges of all of the real-time scheduling
policies described and the strongest priority in the priority range for is weaker than the weakest priority in the pri-
ority ranges for any of the other policies, and
A timeshare scheduling policy with nondecaying priorities.
For processes executing under this policy, the implementation can use only priorities within the range returned by the
functions and when is provided as the parameter. The priority range for the policy is a subset of the priority range
supported by the policy. Note that for the scheduling policy, smaller numbers represent higher (stronger) priorities,
which is the opposite of the POSIX scheduling policies.
The priority value of a thread executing with the policy is not decayed or boosted by the operating system scheduler.
For policy, the priority value of the thread is decayed as the thread consumes processor cycles and boosted when the
thread waits for processor cycles.
The threads in different processor sets do not compete with one another for processors based on their scheduling policy and priority val-
ues. The scheduler looks only at threads assigned to a processor's processor set to choose the next thread to run. A process with lower
scheduling priority in one processor set may be executing while another process in another processor set with higher scheduling priority is
waiting for the processor resources. This is applicable for all scheduling policies.
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 the or the privilege. Processes owned by the superuser have these
privileges. Processes owned by other users may have these privileges, depending on system configuration. See privileges(5) for more
information about privileged access on systems that support fine-grained privileges.
RETURN VALUE
The functions return the following values:
sched_getparam(), sched_rr_get_interval(), sched_setparam(), sched_yield()
Successful completion.
Failure.
is set to indicate the error.
sched_setscheduler()
Successful completion.
n is the former scheduling policy of the specified process.
Failure.
The policy and scheduling parameters remain unchanged. is set to indicate the error.
sched_getscheduler()
Successful completion.
n is the scheduling policy of the specified process.
Failure.
is set to indicate the error.
sched_get_priority_max(), sched_get_priority_min()
Successful completion.
n is the maximum or minimum value, respectively.
Failure.
is set to indicate the error.
PRI_HPUX_TO_POSIX()
Successful completion.
n is the POSIX.4 priority corresponding to pri.
PRI_POSIX_TO_HPUX()
Successful completion.
n is the the HP-UX priority corresponding to pri.
ERRORS
If the functions fail, is set to one of the following values.
sched_setparam()
The target process could not be accessed due to compartmental
restrictions.
The param argument points to an invalid address.
One or more of the requested scheduling parameters is outside the range
defined for the scheduling policy of the specified pid.
The function is not supported by this implementation.
The requesting process does not have permission to set the scheduling
parameters for the specified process, or does not have the privilege to invoke
No process can be found corresponding to that specified by
pid.
sched_getparam()
The target process could not be accessed due to compartmental
restrictions.
The param argument points to an invalid address.
The function is not supported by this implementation.
No process can be found corresponding to that specified by
pid.
sched_setscheduler()
The target process could not be accessed due to compartmental
restrictions.
The param argument points to an invalid address.
The value of the
policy parameter is invalid, or one or more of the parameters contained in param is outside the valid range for the
specified scheduling policy.
The function is not supported by this implementation.
The requesting process does not have permission to set the
scheduling policy of the specified process.
No process can be found corresponding to that specified by
pid.
sched_getscheduler()
The target process could not be accessed due to compartmental
restrictions.
The function is not supported by this implementation.
No process can be found corresponding to that specified by
pid.
sched_yield()
The function is not supported by this implementation.
sched_get_priority_max(), sched_get_priority_min()
The value of the
policy parameter does not represent a defined scheduling policy.
The function is not supported by this implementation.
sched_rr_get_interval()
The function is not supported by this implementation.
No process can be found corresponding to that specified by
pid.
EXAMPLES
Change the calling process to use the strongest priority:
AUTHOR
The functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14.
and were developed by HP.
SEE ALSO
rtsched(1), rtprio(2), privileges(5).
STANDARDS CONFORMANCE
rtsched(2)