1.\" $NetBSD: sched.3,v 1.12 2016/02/20 16:00:10 riastradh Exp $ 2.\" 3.\" Copyright (c) 2008 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 December 4, 2011 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.Nd process scheduling 43.Sh LIBRARY 44.Lb librt 45.Sh SYNOPSIS 46.In sched.h 47.Ft int 48.Fn sched_setparam "pid_t pid" "const struct sched_param *param" 49.Ft int 50.Fn sched_getparam "pid_t pid" "struct sched_param *param" 51.Ft int 52.Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param" 53.Ft int 54.Fn sched_getscheduler "pid_t pid" 55.Ft int 56.Fn sched_get_priority_max "int policy" 57.Ft int 58.Fn sched_get_priority_min "int policy" 59.Ft int 60.Fn sched_rr_get_interval "pid_t pid" "struct timespec *interval" 61.Ft int 62.Fn sched_yield "void" 63.Sh DESCRIPTION 64This section describes the functions used to get scheduling information 65about processes, and control the scheduling of processes. 66.Pp 67Available scheduling policies (classes) are: 68.Bl -tag -width SCHED_OTHER 69.It Dv SCHED_OTHER 70Time-sharing (TS) scheduling policy. 71The default policy in 72.Nx . 73.It Dv SCHED_FIFO 74First in, first out (FIFO) scheduling policy. 75.It Dv SCHED_RR 76Round robin scheduling policy. 77.El 78.Pp 79The 80.Fa struct sched_param 81contains at least one member: 82.Bl -tag -width flags 83.It Fa sched_priority 84Specifies the priority of the process. 85For 86.Dv SCHED_OTHER , 87must be 88.Dv PRI_NONE ; 89the kernel will dynamically assign priorities to the thread based on 90CPU load. 91.El 92.Sh FUNCTIONS 93.Bl -tag -width compact 94.It Fn sched_setparam pid param 95Sets the scheduling parameters for the process specified by 96.Fa pid 97to 98.Fa param . 99If the value of 100.Fa pid 101is equal to zero, then the calling process is used. 102.It Fn sched_getparam pid param 103Gets the scheduling parameters of the process specified by 104.Fa pid 105into the structure 106.Fa param . 107If the value of 108.Fa pid 109is equal to zero, then the calling process is used. 110.It Fn sched_setscheduler pid policy param 111Set the scheduling policy and parameters for the process specified by 112.Fa pid . 113If the value of 114.Fa pid 115is equal to zero, then the calling process is used. 116.It Fn sched_getscheduler pid 117Returns the scheduling policy of the process specified by 118.Fa pid . 119If the value of 120.Fa pid 121is equal to zero, then the calling process is used. 122.It Fn sched_get_priority_max policy 123Returns the maximal priority which may be used for the scheduling policy 124specified by 125.Fa policy . 126.It Fn sched_get_priority_min policy 127Returns the minimal priority which may be used for the scheduling policy 128specified by 129.Fa policy . 130.It Fn sched_rr_get_interval pid interval 131Returns the time quantum into the structure 132.Fa interval 133of the process specified by 134.Fa pid . 135If the value of 136.Fa pid 137is equal to zero, then the calling process is used. 138The process must be running at 139.Fa SCHED_RR 140scheduling policy. 141.It Fn sched_yield 142Yields a processor voluntarily and gives other threads a chance to run 143without waiting for an involuntary preemptive switch. 144.It Fn sched_setaffinity_np pid size cpuset 145Set the affinity mask specified by 146.Fa cpuset 147for the process specified by 148.Fa pid . 149At least one valid CPU must be set in the mask. 150.It Fn sched_getaffinity_np pid size cpuset 151Get the affinity mask of the process specified by 152.Fa pid 153into the 154.Fa cpuset . 155.El 156.Sh IMPLEMENTATION NOTES 157Setting CPU 158.Xr affinity 3 159requires super-user privileges. 160Ordinary users can be allowed to control CPU affinity 161of their threads via the 162.Pa security.models.extensions.user_set_cpu_affinity 163.Xr sysctl 7 . 164See 165.Xr secmodel_extensions 9 . 166.Pp 167Portable applications should not use the 168.Fn sched_setaffinity_np 169and 170.Fn sched_getaffinity_np 171functions. 172.Sh RETURN VALUES 173.Fn sched_setparam , 174.Fn sched_getparam , 175.Fn sched_rr_get_interval , 176and 177.Fn sched_yield 178return 0 on success. 179Otherwise, \-1 is returned and 180.Va errno 181is set to indicate the error. 182.Pp 183.Fn sched_setscheduler 184returns the previously used scheduling policy on success. 185Otherwise, \-1 is returned and 186.Va errno 187is set to indicate the error. 188.Pp 189.Fn sched_getscheduler 190returns the scheduling policy on success. 191Otherwise, \-1 is returned and 192.Va errno 193is set to indicate the error. 194.Pp 195.Fn sched_get_priority_max 196and 197.Fn sched_get_priority_min 198return the maximal/minimal priority value on success. 199Otherwise, \-1 is returned and 200.Va errno 201is set to indicate the error. 202.Pp 203.Fn sched_setaffinity_np 204and 205.Fn sched_getaffinity_np 206return 0 on success. 207Otherwise, \-1 is returned and 208.Va errno 209is set to indicate the error. 210.Sh ERRORS 211The 212.Fn sched_setparam 213and 214.Fn sched_setscheduler 215functions fail if: 216.Bl -tag -width Er 217.It Bq Er EINVAL 218At least one of the specified scheduling parameters was invalid. 219.It Bq Er EPERM 220The calling process has no appropriate privileges to perform the operation. 221.It Bq Er ESRCH 222No process can be found corresponding to the PID specified by 223.Fa pid , 224and the value of 225.Fa pid 226is not zero. 227.El 228.Pp 229The 230.Fn sched_getparam 231and 232.Fn sched_getscheduler 233functions fail if: 234.Bl -tag -width Er 235.It Bq Er EPERM 236The calling process is not a super-user and its effective user id does not 237match the effective user-id of the specified process. 238.It Bq Er ESRCH 239No process can be found corresponding to that specified by 240.Fa pid , 241and the value of 242.Fa pid 243is not zero. 244.El 245.Pp 246The 247.Fn sched_get_priority_max 248and 249.Fn sched_get_priority_min 250functions fail if: 251.Bl -tag -width Er 252.It Bq Er EINVAL 253The specified scheduling policy is invalid. 254.El 255.Pp 256The 257.Fn sched_rr_get_interval 258function fails if: 259.Bl -tag -width Er 260.It Bq Er ESRCH 261No process can be found corresponding to that specified by 262.Fa pid , 263and the value of 264.Fa pid 265is not zero. 266.El 267.Sh SEE ALSO 268.Xr affinity 3 , 269.Xr cpuset 3 , 270.Xr pset 3 , 271.Xr schedctl 8 272.Sh STANDARDS 273These functions, except 274.Fn sched_setaffinity_np 275and 276.Fn sched_getaffinity_np , 277are expected to conform the 278.St -p1003.1-2001 279standard. 280.Sh HISTORY 281The scheduling functions appeared in 282.Nx 5.0 . 283