1.\" $NetBSD: sched.3,v 1.18 2016/09/15 07:53:59 njoly Exp $ 2.\" 3.\" Copyright (c) 2008, 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 5, 2016 31.Dt SCHED 3 32.Os 33.Sh NAME 34.Nm sched_setparam , 35.Nm sched_getparam , 36.Nm sched_setscheduler , 37.Nm sched_getscheduler , 38.Nm sched_get_priority_max , 39.Nm sched_get_priority_min , 40.Nm sched_rr_get_interval , 41.Nm sched_yield , 42.Nm sched_protect , 43.Nm sched_setaffinity_np , 44.Nm sched_getaffinity_np 45.Nd process scheduling 46.Sh LIBRARY 47.Lb librt 48.Sh SYNOPSIS 49.In sched.h 50.Ft int 51.Fn sched_setparam "pid_t pid" "const struct sched_param *param" 52.Ft int 53.Fn sched_getparam "pid_t pid" "struct sched_param *param" 54.Ft int 55.Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param" 56.Ft int 57.Fn sched_getscheduler "pid_t pid" 58.Ft int 59.Fn sched_get_priority_max "int policy" 60.Ft int 61.Fn sched_get_priority_min "int policy" 62.Ft int 63.Fn sched_rr_get_interval "pid_t pid" "struct timespec *interval" 64.Ft int 65.Fn sched_yield "void" 66.Ft int 67.Fn sched_setaffinity_np "pid_t pid" "size_t size" "cpuset_t *cpuset" 68.Ft int 69.Fn sched_getaffinity_np "pid_t pid" "size_t size" "cpuset_t *cpuset" 70.Ft int 71.Fn sched_protect "int priority" 72.Sh DESCRIPTION 73This section describes the functions used to get scheduling information 74about processes, and control the scheduling of processes. 75.Pp 76Available scheduling policies (classes) are: 77.Bl -tag -width SCHED_OTHER 78.It Dv SCHED_OTHER 79Time-sharing (TS) scheduling policy. 80The default policy in 81.Nx . 82.It Dv SCHED_FIFO 83First in, first out (FIFO) scheduling policy. 84.It Dv SCHED_RR 85Round robin scheduling policy. 86.El 87.Pp 88The 89.Fa struct sched_param 90contains at least one member: 91.Bl -tag -width flags 92.It Fa sched_priority 93Specifies the priority of the process. 94For 95.Dv SCHED_OTHER , 96must be 97.Dv PRI_NONE ; 98the kernel will dynamically assign priorities to the thread based on 99CPU load. 100.El 101.Sh FUNCTIONS 102.Bl -tag -width compact 103.It Fn sched_setparam pid param 104Sets the scheduling parameters for the process specified by 105.Fa pid 106to 107.Fa param . 108If the value of 109.Fa pid 110is equal to zero, then the calling process is used. 111.It Fn sched_getparam pid param 112Gets the scheduling parameters of the process specified by 113.Fa pid 114into the structure 115.Fa param . 116If the value of 117.Fa pid 118is equal to zero, then the calling process is used. 119.It Fn sched_setscheduler pid policy param 120Set the scheduling policy and parameters for the process specified by 121.Fa pid . 122If the value of 123.Fa pid 124is equal to zero, then the calling process is used. 125.It Fn sched_getscheduler pid 126Returns the scheduling policy of the process specified by 127.Fa pid . 128If the value of 129.Fa pid 130is equal to zero, then the calling process is used. 131.It Fn sched_get_priority_max policy 132Returns the maximal priority which may be used for the scheduling policy 133specified by 134.Fa policy . 135.It Fn sched_get_priority_min policy 136Returns the minimal priority which may be used for the scheduling policy 137specified by 138.Fa policy . 139.It Fn sched_rr_get_interval pid interval 140Returns the time quantum into the structure 141.Fa interval 142of the process specified by 143.Fa pid . 144If the value of 145.Fa pid 146is equal to zero, then the calling process is used. 147The process must be running at 148.Fa SCHED_RR 149scheduling policy. 150.It Fn sched_yield 151Yields a processor voluntarily and gives other threads a chance to run 152without waiting for an involuntary preemptive switch. 153.It Fn sched_setaffinity_np pid size cpuset 154Set the affinity mask specified by 155.Fa cpuset 156for the process specified by 157.Fa pid . 158At least one valid CPU must be set in the mask. 159.It Fn sched_getaffinity_np pid size cpuset 160Get the affinity mask of the process specified by 161.Fa pid 162into the 163.Fa cpuset . 164.It Fn sched_protect priority 165Performs priority protection using the 166.Dv PTHREAD_PRIO_PROTECT 167protocol. 168This function will increase the protected priority of the caller thread to 169.Fa priority 170if the current thread's protected priority is smaller than 171.Fa priority . 172Multiple calls to 173.Fn sched_protect 174with a positive priority will 175.Dq push 176a priority level to the current thread, whereas calling 177.Fn sched_protect 178with a 179.Fa priority 180level of 181.Dv \-1 182will 183.Dq pop 184a priority level. 185When the level reaches 186.Dv 0 187(the same number of 188.Dq pushes 189and 190.Dq pops 191have been issued) the original thread priority will be restored. 192.El 193.Sh IMPLEMENTATION NOTES 194Setting CPU 195.Xr affinity 3 196requires super-user privileges. 197Ordinary users can be allowed to control CPU affinity 198of their threads via the 199.Pa security.models.extensions.user_set_cpu_affinity 200.Xr sysctl 7 . 201See 202.Xr secmodel_extensions 9 . 203.Pp 204Portable applications should not use the 205.Fn sched_setaffinity_np 206and 207.Fn sched_getaffinity_np 208functions. 209.Sh RETURN VALUES 210.Fn sched_protect , 211.Fn sched_setparam , 212.Fn sched_getparam , 213.Fn sched_rr_get_interval , 214and 215.Fn sched_yield 216return 0 on success. 217Otherwise, \-1 is returned and 218.Va errno 219is set to indicate the error. 220.Pp 221.Fn sched_setscheduler 222returns the previously used scheduling policy on success. 223Otherwise, \-1 is returned and 224.Va errno 225is set to indicate the error. 226.Pp 227.Fn sched_getscheduler 228returns the scheduling policy on success. 229Otherwise, \-1 is returned and 230.Va errno 231is set to indicate the error. 232.Pp 233.Fn sched_get_priority_max 234and 235.Fn sched_get_priority_min 236return the maximal/minimal priority value on success. 237Otherwise, \-1 is returned and 238.Va errno 239is set to indicate the error. 240.Pp 241.Fn sched_setaffinity_np 242and 243.Fn sched_getaffinity_np 244return 0 on success. 245Otherwise, \-1 is returned and 246.Va errno 247is set to indicate the error. 248.Sh ERRORS 249The 250.Fn sched_setparam 251and 252.Fn sched_setscheduler 253functions fail if: 254.Bl -tag -width Er 255.It Bq Er EINVAL 256At least one of the specified scheduling parameters was invalid. 257.It Bq Er EPERM 258The calling process has no appropriate privileges to perform the operation. 259.It Bq Er ESRCH 260No process can be found corresponding to the PID specified by 261.Fa pid , 262and the value of 263.Fa pid 264is not zero. 265.El 266.Pp 267The 268.Fn sched_getparam 269and 270.Fn sched_getscheduler 271functions fail if: 272.Bl -tag -width Er 273.It Bq Er EPERM 274The calling process is not a super-user and its effective user id does not 275match the effective user-id of the specified process. 276.It Bq Er ESRCH 277No process can be found corresponding to that specified by 278.Fa pid , 279and the value of 280.Fa pid 281is not zero. 282.El 283.Pp 284The 285.Fn sched_get_priority_max 286and 287.Fn sched_get_priority_min 288functions fail if: 289.Bl -tag -width Er 290.It Bq Er EINVAL 291The specified scheduling policy is invalid. 292.El 293.Pp 294The 295.Fn sched_rr_get_interval 296function fails if: 297.Bl -tag -width Er 298.It Bq Er ESRCH 299No process can be found corresponding to that specified by 300.Fa pid , 301and the value of 302.Fa pid 303is not zero. 304.El 305.Pp 306The 307.Fn sched_protect 308function fails if: 309.Bl -tag -width Er 310.It Bq Er EINVAL 311The thread was not priority protected. 312.It Bq Er EPERM 313The 314.Fa priority 315parameter was out of range (not in the range between 316.Dv SCHED_PRIO_MIN 317and 318.Dv SCHED_PRIO_MAX ) . 319.El 320.Sh SEE ALSO 321.Xr affinity 3 , 322.Xr cpuset 3 , 323.Xr pset 3 , 324.Xr schedctl 8 325.Sh STANDARDS 326These functions, except 327.Fn sched_setaffinity_np 328and 329.Fn sched_getaffinity_np , 330are expected to conform the 331.St -p1003.1-2001 332standard. 333.Sh HISTORY 334The scheduling functions appeared in 335.Nx 5.0 . 336