.\"	$NetBSD: sched.3,v 1.18 2016/09/15 07:53:59 njoly Exp $
.\"
.\" Copyright (c) 2008, 2016 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 5, 2016
.Dt SCHED 3
.Os
.Sh NAME
.Nm sched_setparam ,
.Nm sched_getparam ,
.Nm sched_setscheduler ,
.Nm sched_getscheduler ,
.Nm sched_get_priority_max ,
.Nm sched_get_priority_min ,
.Nm sched_rr_get_interval ,
.Nm sched_yield ,
.Nm sched_protect ,
.Nm sched_setaffinity_np ,
.Nm sched_getaffinity_np
.Nd process scheduling
.Sh LIBRARY
.Lb librt
.Sh SYNOPSIS
.In sched.h
.Ft int
.Fn sched_setparam "pid_t pid" "const struct sched_param *param"
.Ft int
.Fn sched_getparam "pid_t pid" "struct sched_param *param"
.Ft int
.Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param"
.Ft int
.Fn sched_getscheduler "pid_t pid"
.Ft int
.Fn sched_get_priority_max "int policy"
.Ft int
.Fn sched_get_priority_min "int policy"
.Ft int
.Fn sched_rr_get_interval "pid_t pid" "struct timespec *interval"
.Ft int
.Fn sched_yield "void"
.Ft int
.Fn sched_setaffinity_np "pid_t pid" "size_t size" "cpuset_t *cpuset"
.Ft int
.Fn sched_getaffinity_np "pid_t pid" "size_t size" "cpuset_t *cpuset"
.Ft int
.Fn sched_protect "int priority"
.Sh DESCRIPTION
This section describes the functions used to get scheduling information
about processes, and control the scheduling of processes.
.Pp
Available scheduling policies (classes) are:
.Bl -tag -width SCHED_OTHER
.It Dv SCHED_OTHER
Time-sharing (TS) scheduling policy.
The default policy in
.Nx .
.It Dv SCHED_FIFO
First in, first out (FIFO) scheduling policy.
.It Dv SCHED_RR
Round robin scheduling policy.
.El
.Pp
The
.Fa struct sched_param
contains at least one member:
.Bl -tag -width flags
.It Fa sched_priority
Specifies the priority of the process.
For
.Dv SCHED_OTHER ,
must be
.Dv PRI_NONE ;
the kernel will dynamically assign priorities to the thread based on
CPU load.
.El
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn sched_setparam pid param
Sets the scheduling parameters for the process specified by
.Fa pid
to
.Fa param .
If the value of
.Fa pid
is equal to zero, then the calling process is used.
.It Fn sched_getparam pid param
Gets the scheduling parameters of the process specified by
.Fa pid
into the structure
.Fa param .
If the value of
.Fa pid
is equal to zero, then the calling process is used.
.It Fn sched_setscheduler pid policy param
Set the scheduling policy and parameters for the process specified by
.Fa pid .
If the value of
.Fa pid
is equal to zero, then the calling process is used.
.It Fn sched_getscheduler pid
Returns the scheduling policy of the process specified by
.Fa pid .
If the value of
.Fa pid
is equal to zero, then the calling process is used.
.It Fn sched_get_priority_max policy
Returns the maximal priority which may be used for the scheduling policy
specified by
.Fa policy .
.It Fn sched_get_priority_min policy
Returns the minimal priority which may be used for the scheduling policy
specified by
.Fa policy .
.It Fn sched_rr_get_interval pid interval
Returns the time quantum into the structure
.Fa interval
of the process specified by
.Fa pid .
If the value of
.Fa pid
is equal to zero, then the calling process is used.
The process must be running at
.Fa SCHED_RR
scheduling policy.
.It Fn sched_yield
Yields a processor voluntarily and gives other threads a chance to run
without waiting for an involuntary preemptive switch.
.It Fn sched_setaffinity_np pid size cpuset
Set the affinity mask specified by
.Fa cpuset
for the process specified by
.Fa pid .
At least one valid CPU must be set in the mask.
.It Fn sched_getaffinity_np pid size cpuset
Get the affinity mask of the process specified by
.Fa pid
into the
.Fa cpuset .
.It Fn sched_protect priority
Performs priority protection using the
.Dv PTHREAD_PRIO_PROTECT
protocol.
This function will increase the protected priority of the caller thread to
.Fa priority
if the current thread's protected priority is smaller than
.Fa priority .
Multiple calls to
.Fn sched_protect
with a positive priority will
.Dq push
a priority level to the current thread, whereas calling
.Fn sched_protect
with a
.Fa priority
level of
.Dv \-1
will
.Dq pop
a priority level.
When the level reaches
.Dv 0
(the same number of
.Dq pushes
and
.Dq pops
have been issued) the original thread priority will be restored.
.El
.Sh IMPLEMENTATION NOTES
Setting CPU
.Xr affinity 3
requires super-user privileges.
Ordinary users can be allowed to control CPU affinity
of their threads via the
.Pa security.models.extensions.user_set_cpu_affinity
.Xr sysctl 7 .
See
.Xr secmodel_extensions 9 .
.Pp
Portable applications should not use the
.Fn sched_setaffinity_np
and
.Fn sched_getaffinity_np
functions.
.Sh RETURN VALUES
.Fn sched_protect ,
.Fn sched_setparam ,
.Fn sched_getparam ,
.Fn sched_rr_get_interval ,
and
.Fn sched_yield
return 0 on success.
Otherwise, \-1 is returned and
.Va errno
is set to indicate the error.
.Pp
.Fn sched_setscheduler
returns the previously used scheduling policy on success.
Otherwise, \-1 is returned and
.Va errno
is set to indicate the error.
.Pp
.Fn sched_getscheduler
returns the scheduling policy on success.
Otherwise, \-1 is returned and
.Va errno
is set to indicate the error.
.Pp
.Fn sched_get_priority_max
and
.Fn sched_get_priority_min
return the maximal/minimal priority value on success.
Otherwise, \-1 is returned and
.Va errno
is set to indicate the error.
.Pp
.Fn sched_setaffinity_np
and
.Fn sched_getaffinity_np
return 0 on success.
Otherwise, \-1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn sched_setparam
and
.Fn sched_setscheduler
functions fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
At least one of the specified scheduling parameters was invalid.
.It Bq Er EPERM
The calling process has no appropriate privileges to perform the operation.
.It Bq Er ESRCH
No process can be found corresponding to the PID specified by
.Fa pid ,
and the value of
.Fa pid
is not zero.
.El
.Pp
The
.Fn sched_getparam
and
.Fn sched_getscheduler
functions fail if:
.Bl -tag -width Er
.It Bq Er 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.
.It Bq Er ESRCH
No process can be found corresponding to that specified by
.Fa pid ,
and the value of
.Fa pid
is not zero.
.El
.Pp
The
.Fn sched_get_priority_max
and
.Fn sched_get_priority_min
functions fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The specified scheduling policy is invalid.
.El
.Pp
The
.Fn sched_rr_get_interval
function fails if:
.Bl -tag -width Er
.It Bq Er ESRCH
No process can be found corresponding to that specified by
.Fa pid ,
and the value of
.Fa pid
is not zero.
.El
.Pp
The
.Fn sched_protect
function fails if:
.Bl -tag -width Er
.It Bq Er EINVAL
The thread was not priority protected.
.It Bq Er EPERM
The
.Fa priority
parameter was out of range (not in the range between
.Dv SCHED_PRIO_MIN
and
.Dv SCHED_PRIO_MAX ) .
.El
.Sh SEE ALSO
.Xr affinity 3 ,
.Xr cpuset 3 ,
.Xr pset 3 ,
.Xr schedctl 8
.Sh STANDARDS
These functions, except
.Fn sched_setaffinity_np
and
.Fn sched_getaffinity_np ,
are expected to conform the
.St -p1003.1-2001
standard.
.Sh HISTORY
The scheduling functions appeared in
.Nx 5.0 .