sched_setscheduler Subroutine

Edit online

Purpose

Sets the scheduling policy and parameters.

Library

Standard C Library (libc.a)

Syntax

#include <sched.h>

int sched_setscheduler (pid, policy, param)
pid_t pid;
int policy;
const struct sched_param *param;

Description

The sched_setscheduler subroutine sets the scheduling policy and scheduling parameters of the process specified by the pid parameter to the policy parameter and the parameters specified in the sched_param structure pointed to by param, respectively. The value of the sched_priority member in the sched_param structure is any integer within the inclusive priority range for the scheduling policy.

The possible values for the policy parameter are defined in the sched.h header file.

If a process specified by the pid parameter exists, and if the calling process has permission, the scheduling policy and scheduling parameters are set for the process.

If the pid parameter is zero, the scheduling policy and scheduling parameters are set for the calling process.

In order to change a scheduling policy to a fixed priority scheduling policy, the caller must have SET_PROC_RAC authority. When changing the scheduling policy to the SCHED_OTHER scheduling policy, if the former policy was not SCHED_OTHER, the caller must have SET_PROC_RAC authority.

SET_PROC_RAC authority is not needed if the caller wants to defavor a process under the following conditions:
  • The former_policy process was SCHED_OTHER.
  • The new policy is still SCHED_OTHER.
  • The new priority is lower than the old priority (the caller wants to defavor the process).
  • All the impacted user process-scope threads have a SCHED_OTHER policy.
  • The caller should have the same effective or real user id or BYPASS_DAC_WRITE authority.

The sched_setscheduler subroutine is successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by pid to the values specified by the policy parameter and the structure pointed to by the param parameter, respectively.

The effect of this subroutine on individual threads is dependent on the scheduling contention scope of the following threads:
  • The sched_setscheduler subroutine has no effect on threads with system scheduling contention scope.
  • For threads with process scheduling contention scope, the threads' scheduling policy and associated parameters are not affected. However, the scheduling of these threads with respect to threads in other processes might be dependent on the scheduling parameters of their process, which are governed using the sched_setscheduler subroutine.

If an implementation supports a two-level scheduling model in which library threads are multiplexed on top of several kernel-scheduled entities, the underlying kernel-scheduled entities for the system contention scope threads are not affected by these subroutines.

The underlying kernel-scheduled entities for the process contention scope threads have their scheduling policy and associated scheduling parameters changed to the values specified in the policy and param parameters, respectively. 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.

This subroutine is not atomic with respect to other threads in the process. Threads may continue to execute while this subroutine is in the process of changing the scheduling policy and associated scheduling parameters for the underlying kernel-scheduled entities used by the process contention scope threads.

Parameters

Item Description
pid Specifies the process for which the scheduling policy and parameters are set.
policy Contains the scheduling policy and scheduling parameters settings.
param Points to the sched_param structure.

Return Values

Upon successful completion, the sched_setscheduler subroutine returns the former scheduling policy of the specified process. If the sched_setscheduler subroutine fails to complete successfully, the policy and scheduling parameters will remain unchanged, and the subroutine returns -1 and sets errno to indicate the error.

Error Codes

The sched_setscheduler subroutine fails if:
Item Description
EINVAL The param parameter is null or a bad address.
ENOTSUP This interface does not support processes capable of checkpoint.
EPERM The requesting process does not have permission to set either or both of the scheduling parameters or the scheduling policy of the specified process.
ESRCH The pid parameter is negative, or no process can be found that corresponds to the one specified by the pid parameter.