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