Home | History | Annotate | Line # | Download | only in librt 
 $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
n 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.

p
Available scheduling policies (classes) are:
l -tag -width SCHED_OTHER t Dv SCHED_OTHER Time-sharing (TS) scheduling policy.
The default policy in
.Nx .
t Dv SCHED_FIFO First in, first out (FIFO) scheduling policy.
t Dv SCHED_RR Round robin scheduling policy.
.El

p
The
.Fa struct sched_param
contains at least one member:
l -tag -width flags t 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
l -tag -width compact t 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.
t 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.
t 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.
t 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.
t Fn sched_get_priority_max policy Returns the maximal priority which may be used for the scheduling policy
specified by
.Fa policy .
t Fn sched_get_priority_min policy Returns the minimal priority which may be used for the scheduling policy
specified by
.Fa policy .
t 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.
t Fn sched_yield Yields a processor voluntarily and gives other threads a chance to run
without waiting for an involuntary preemptive switch.
t 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.
t Fn sched_getaffinity_np pid size cpuset Get the affinity mask of the process specified by
.Fa pid
into the
.Fa cpuset .
t 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

a security.models.extensions.user_set_cpu_affinity
.Xr sysctl 7 .
See
.Xr secmodel_extensions 9 .

p
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.

p
.Fn sched_setscheduler
returns the previously used scheduling policy on success.
Otherwise, -1 is returned and
.Va errno
is set to indicate the error.

p
.Fn sched_getscheduler
returns the scheduling policy on success.
Otherwise, -1 is returned and
.Va errno
is set to indicate the error.

p
.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.

p
.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:
l -tag -width Er t Bq Er EINVAL At least one of the specified scheduling parameters was invalid.
t Bq Er EPERM The calling process has no appropriate privileges to perform the operation.
t 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

p
The
.Fn sched_getparam
and
.Fn sched_getscheduler
functions fail if:
l -tag -width Er t 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.
t 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

p
The
.Fn sched_get_priority_max
and
.Fn sched_get_priority_min
functions fail if:
l -tag -width Er t Bq Er EINVAL The specified scheduling policy is invalid.
.El

p
The
.Fn sched_rr_get_interval
function fails if:
l -tag -width Er t 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

p
The
.Fn sched_protect
function fails if:
l -tag -width Er t Bq Er EINVAL The thread was not priority protected.
t 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 .