SCHED(3)

SCHED(3) | Library Functions Manual | SCHED(3)

# NAME

`sched_setparam`, `sched_getparam`, `sched_setscheduler`, `sched_getscheduler`, `sched_get_priority_max`, `sched_get_priority_min`, `sched_rr_get_interval`, `sched_yield`, `sched_protect`, `sched_setaffinity_np`, `sched_getaffinity_np` —
process scheduling

# LIBRARY

POSIX Real-time Library (librt, -lrt)

# SYNOPSIS

`#include <sched.h>`

int
`sched_setparam`(pid_t pid, const struct sched_param *param);

int
`sched_getparam`(pid_t pid, struct sched_param *param);

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

int
`sched_getscheduler`(pid_t pid);

int
`sched_get_priority_max`(int policy);

int
`sched_get_priority_min`(int policy);

int
`sched_rr_get_interval`(pid_t pid, struct timespec *interval);

int
`sched_yield`(void);

int
`sched_setaffinity_np`(pid_t pid, size_t size, cpuset_t *cpuset);

int
`sched_getaffinity_np`(pid_t pid, size_t size, cpuset_t *cpuset);

int
`sched_protect`(int priority);

# DESCRIPTION

This section describes the functions used to get scheduling information about processes, and control the scheduling of processes.

Available scheduling policies (classes) are:

`SCHED_OTHER`
  Time-sharing (TS) scheduling policy. The default policy in NetBSD.
`SCHED_FIFO`
  First in, first out (FIFO) scheduling policy.
`SCHED_RR`
  Round robin scheduling policy.

The struct sched_param contains at least one member:

sched_priority
  Specifies the priority of the process. For `SCHED_OTHER`, must be `PRI_NONE`; the kernel will dynamically assign priorities to the thread based on CPU load.

# FUNCTIONS

`sched_setparam`(pid, param)
  Sets the scheduling parameters for the process specified by pid to param. If the value of pid is equal to zero, then the calling process is used.
`sched_getparam`(pid, param)
  Gets the scheduling parameters of the process specified by pid into the structure param. If the value of pid is equal to zero, then the calling process is used.
`sched_setscheduler`(pid, policy, param)
  Set the scheduling policy and parameters for the process specified by pid. If the value of pid is equal to zero, then the calling process is used.
`sched_getscheduler`(pid)
  Returns the scheduling policy of the process specified by pid. If the value of pid is equal to zero, then the calling process is used.
`sched_get_priority_max`(policy)
  Returns the maximal priority which may be used for the scheduling policy specified by policy.
`sched_get_priority_min`(policy)
  Returns the minimal priority which may be used for the scheduling policy specified by policy.
`sched_rr_get_interval`(pid, interval)
  Returns the time quantum into the structure interval of the process specified by pid. If the value of pid is equal to zero, then the calling process is used. The process must be running at SCHED_RR scheduling policy.
`sched_yield`()
  Yields a processor voluntarily and gives other threads a chance to run without waiting for an involuntary preemptive switch.
`sched_setaffinity_np`(pid, size, cpuset)
  Set the affinity mask specified by cpuset for the process specified by pid. At least one valid CPU must be set in the mask.
`sched_getaffinity_np`(pid, size, cpuset)
  Get the affinity mask of the process specified by pid into the cpuset.
`sched_protect`(priority)
  Performs priority protection using the `PTHREAD_PRIO_PROTECT` protocol. This function will increase the protected priority of the caller thread to priority if the current thread's protected priority is smaller than priority. Multiple calls to `sched_protect`() with a positive priority will “push” a priority level to the current thread, whereas calling `sched_protect`() with a priority level of `-1` will “pop” a priority level. When the level reaches `0` (the same number of “pushes” and “pops” have been issued) the original thread priority will be restored.

# IMPLEMENTATION NOTES

Setting CPU affinity(3) requires super-user privileges. Ordinary users can be allowed to control CPU affinity of their threads via the security.models.extensions.user_set_cpu_affinity sysctl(7). See secmodel_extensions(9).

Portable applications should not use the `sched_setaffinity_np`() and `sched_getaffinity_np`() functions.

# RETURN VALUES

`sched_protect`(), `sched_setparam`(), `sched_getparam`(), `sched_rr_get_interval`(), and `sched_yield`() return 0 on success. Otherwise, -1 is returned and errno is set to indicate the error.

`sched_setscheduler`() returns the previously used scheduling policy on success. Otherwise, -1 is returned and errno is set to indicate the error.

`sched_getscheduler`() returns the scheduling policy on success. Otherwise, -1 is returned and errno is set to indicate the error.

`sched_get_priority_max`() and `sched_get_priority_min`() return the maximal/minimal priority value on success. Otherwise, -1 is returned and errno is set to indicate the error.

`sched_setaffinity_np`() and `sched_getaffinity_np`() return 0 on success. Otherwise, -1 is returned and errno is set to indicate the error.

# ERRORS

The `sched_setparam`() and `sched_setscheduler`() functions fail if:

[`EINVAL`]
  At least one of the specified scheduling parameters was invalid.
[`EPERM`]
  The calling process has no appropriate privileges to perform the operation.
[`ESRCH`]
  No process can be found corresponding to the PID specified by pid, and the value of pid is not zero.

The `sched_getparam`() and `sched_getscheduler`() functions fail if:

[`EPERM`]
  The calling process is not a super-user and its effective user id does not match the effective user-id of the specified process.
[`ESRCH`]
  No process can be found corresponding to that specified by pid, and the value of pid is not zero.

The `sched_get_priority_max`() and `sched_get_priority_min`() functions fail if:

[`EINVAL`]
  The specified scheduling policy is invalid.

The `sched_rr_get_interval`() function fails if:

[`ESRCH`]
  No process can be found corresponding to that specified by pid, and the value of pid is not zero.

The `sched_protect`() function fails if:

[`EINVAL`]
  The thread was not priority protected.
[`EPERM`]
  The priority parameter was out of range (not in the range between `SCHED_PRIO_MIN` and `SCHED_PRIO_MAX`).

# SEE ALSO

affinity(3), cpuset(3), pset(3), schedctl(8)

# STANDARDS

These functions, except `sched_setaffinity_np`() and `sched_getaffinity_np`(), are expected to conform the IEEE Std 1003.1-2001 (“POSIX.1”) standard.

# HISTORY

The scheduling functions appeared in NetBSD 5.0.

August 5, 2016 | NetBSD 9.4