pthread_setschedparam Subroutine

Purpose

Sets schedpolicy and schedparam attributes of a thread.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>
#include <sys/sched.h>

int pthread_setschedparam (thread, schedpolicy, schedparam)
pthread_t thread;
int schedpolicy;
const struct sched_param *schedparam;

Description

The pthread_setschedparam subroutine dynamically sets the schedpolicy and schedparam attributes of the thread thread. The schedpolicy attribute specifies the scheduling policy of the thread. The schedparam attribute specifies the scheduling parameters of a thread that is created with this attribute object. The sched_priority field of the sched_param structure contains the priority of the thread. It is an integer value.

If the target thread has system contention scope, the process must have root authority to set the scheduling policy to either SCHED_FIFO or SCHED_RR.

Note: The pthread.h header file must be the first included file of each source file that uses the threads library. Otherwise, the -D_THREAD_SAFE compilation flag should be used, or the cc_r compiler used. In this case, the flag is automatically set.

This subroutine is part of the Base Operating System (BOS) Runtime. The implementation of this subroutine depends on the priority scheduling POSIX option. The priority scheduling POSIX option is implemented in the operating system.

Parameters

Table 1. Parameters
Item	Description
`thread`	Specifies the target thread.
`schedpolicy`	Points to the schedpolicy attribute to set. It must have one of the following values: SCHED_FIFO Denotes first-in first-out scheduling. SCHED_RR Denotes round-robin scheduling. SCHED_OTHER Denotes the default operating system scheduling policy. It is the default value. If `schedpolicy` is SCHED_OTHER, then `sched_priority` must be in the range from 40 to 80, where 40 is the least favored priority and 80 is the most favored. Note: Priority of threads with a process contention scope and a SCHED_OTHER policy is controlled by the kernel; thus, setting the priority of such a thread has no effect. However, priority of threads with a system contention scope and a SCHED_OTHER policy can be modified. The modification directly affects the underlying kernel thread `nice` value.
`schedparam`	Points to where the scheduling parameters to set are stored. The sched_priority field must be in the range from 1 to 127, where 1 is the least favored priority, and 127 the most favored. If `schedpolicy` is SCHED_OTHER, then `sched_priority` must be in the range from 40 to 80, where 40 is the least favored priority and 80 is the most favored. Users can change the priority of a thread when setting its scheduling policy to SCHED_OTHER. The legal values that can be passed to pthread_setschedparam range from 40 to 80. Only privileged users can set a priority higher than 60. A value ranging from 1 to 39 provides the same priority as 40, and a value ranging from 81 to 127 provides the same priority as 80.

Return Values

Upon successful completion, 0 is returned. Otherwise, an error code is returned.

Error Codes

The pthread_setschedparam subroutine is unsuccessful if the following is true:

Table 2. Error Codes
Item	Description
`EINVAL`	The `thread` or `schedparam` parameters are not valid.
`ENOSYS`	The priority scheduling POSIX option is not implemented.
`ENOTSUP`	The value of the schedpolicy or schedparam attributes are not supported.
`EPERM`	The target thread has insufficient permission to perform the operation or is already engaged in a mutex protocol.
`ESRCH`	The thread `thread` does not exist.