]>
Commit | Line | Data |
---|---|---|
a98bcd58 | 1 | .\" Copyright (c) International Business Machines orp., 2006 |
5b3b2ce1 | 2 | .\" |
e4a74ca8 | 3 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
5b3b2ce1 MK |
4 | .\" |
5 | .\" HISTORY: | |
6 | .\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com> | |
c11b1abf | 7 | .\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com> |
5b3b2ce1 | 8 | .\" |
5b3b2ce1 | 9 | .\" |
45186a5d | 10 | .TH IOPRIO_SET 2 2021-06-20 "Linux man-pages (unreleased)" |
5b3b2ce1 MK |
11 | .SH NAME |
12 | ioprio_get, ioprio_set \- get/set I/O scheduling class and priority | |
3c45dc0e AC |
13 | .SH LIBRARY |
14 | Standard C library | |
8fc3b2cf | 15 | .RI ( libc ", " \-lc ) |
5b3b2ce1 MK |
16 | .SH SYNOPSIS |
17 | .nf | |
0d961e88 AC |
18 | .BR "#include <linux/ioprio.h> " "/* Definition of " IOPRIO_* " constants */" |
19 | .BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */" | |
20 | .B #include <unistd.h> | |
21 | .PP | |
22 | .BI "int syscall(SYS_ioprio_get, int " which ", int " who ); | |
23 | .BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio ); | |
5b3b2ce1 | 24 | .fi |
dbfe9c70 | 25 | .PP |
45c99e3e | 26 | .IR Note : |
0d961e88 AC |
27 | glibc provides no wrappers for these system calls, |
28 | necessitating the use of | |
29 | .BR syscall (2). | |
5b3b2ce1 MK |
30 | .SH DESCRIPTION |
31 | The | |
32 | .BR ioprio_get () | |
33 | and | |
34 | .BR ioprio_set () | |
83a9c27c | 35 | system calls get and set the I/O scheduling class and |
b91e4e72 | 36 | priority of one or more threads. |
efeece04 | 37 | .PP |
5b3b2ce1 MK |
38 | The |
39 | .I which | |
40 | and | |
41 | .I who | |
b91e4e72 | 42 | arguments identify the thread(s) on which the system |
5b3b2ce1 MK |
43 | calls operate. |
44 | The | |
45 | .I which | |
46 | argument determines how | |
47 | .I who | |
48 | is interpreted, and has one of the following values: | |
49 | .TP | |
50 | .B IOPRIO_WHO_PROCESS | |
51 | .I who | |
b91e4e72 | 52 | is a process ID or thread ID identifying a single process or thread. |
82fdd7c7 MK |
53 | If |
54 | .I who | |
55 | is 0, then operate on the calling thread. | |
5b3b2ce1 MK |
56 | .TP |
57 | .B IOPRIO_WHO_PGRP | |
58 | .I who | |
59 | is a process group ID identifying all the members of a process group. | |
82fdd7c7 MK |
60 | If |
61 | .I who | |
62 | is 0, then operate on the process group of which the caller is a member. | |
5b3b2ce1 MK |
63 | .TP |
64 | .B IOPRIO_WHO_USER | |
65 | .I who | |
66 | is a user ID identifying all of the processes that | |
67 | have a matching real UID. | |
bea08fec | 68 | .\" FIXME . Need to document the behavior when 'who" is specified as 0 |
82fdd7c7 | 69 | .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 |
5b3b2ce1 MK |
70 | .PP |
71 | If | |
9606a1f3 | 72 | .I which |
5b3b2ce1 MK |
73 | is specified as |
74 | .B IOPRIO_WHO_PGRP | |
75 | or | |
76 | .B IOPRIO_WHO_USER | |
77 | when calling | |
78 | .BR ioprio_get (), | |
79 | and more than one process matches | |
80 | .IR who , | |
81 | then the returned priority will be the highest one found among | |
82 | all of the matching processes. | |
83 | One priority is said to be | |
84 | higher than another one if it belongs to a higher priority | |
85 | class | |
86 | .RB ( IOPRIO_CLASS_RT | |
87 | is the highest priority class; | |
88 | .B IOPRIO_CLASS_IDLE | |
89 | is the lowest) | |
90 | or if it belongs to the same priority class as the other process but | |
a98bcd58 | 91 | has a higher priority level (a lower priority number means a |
5b3b2ce1 | 92 | higher priority level). |
efeece04 | 93 | .PP |
5b3b2ce1 MK |
94 | The |
95 | .I ioprio | |
96 | argument given to | |
97 | .BR ioprio_set () | |
98 | is a bit mask that specifies both the scheduling class and the | |
99 | priority to be assigned to the target process(es). | |
100 | The following macros are used for assembling and dissecting | |
101 | .I ioprio | |
102 | values: | |
103 | .TP | |
104 | .BI IOPRIO_PRIO_VALUE( class ", " data ) | |
105 | Given a scheduling | |
106 | .I class | |
107 | and priority | |
108 | .RI ( data ), | |
109 | this macro combines the two values to produce an | |
110 | .I ioprio | |
111 | value, which is returned as the result of the macro. | |
112 | .TP | |
113 | .BI IOPRIO_PRIO_CLASS( mask ) | |
114 | Given | |
0daa9e92 | 115 | .I mask |
5b3b2ce1 | 116 | (an |
0daa9e92 | 117 | .I ioprio |
5b3b2ce1 MK |
118 | value), this macro returns its I/O class component, that is, |
119 | one of the values | |
120 | .BR IOPRIO_CLASS_RT , | |
121 | .BR IOPRIO_CLASS_BE , | |
122 | or | |
123 | .BR IOPRIO_CLASS_IDLE . | |
124 | .TP | |
125 | .BI IOPRIO_PRIO_DATA( mask ) | |
126 | Given | |
0daa9e92 | 127 | .I mask |
5b3b2ce1 | 128 | (an |
0daa9e92 | 129 | .I ioprio |
5b3b2ce1 MK |
130 | value), this macro returns its priority |
131 | .RI ( data ) | |
132 | component. | |
133 | .PP | |
134 | See the NOTES section for more | |
02906043 MK |
135 | information on scheduling classes and priorities, |
136 | as well as the meaning of specifying | |
137 | .I ioprio | |
138 | as 0. | |
efeece04 | 139 | .PP |
682edefb MK |
140 | I/O priorities are supported for reads and for synchronous |
141 | .RB ( O_DIRECT , | |
142 | .BR O_SYNC ) | |
143 | writes. | |
c13182ef | 144 | I/O priorities are not supported for asynchronous |
a98bcd58 MK |
145 | writes because they are issued outside the context of the program |
146 | dirtying the memory, and thus program-specific priorities do not apply. | |
47297adb | 147 | .SH RETURN VALUE |
5b3b2ce1 MK |
148 | On success, |
149 | .BR ioprio_get () | |
150 | returns the | |
151 | .I ioprio | |
152 | value of the process with highest I/O priority of any of the processes | |
153 | that match the criteria specified in | |
154 | .I which | |
155 | and | |
156 | .IR who . | |
157 | On error, \-1 is returned, and | |
158 | .I errno | |
159 | is set to indicate the error. | |
160 | .PP | |
161 | On success, | |
162 | .BR ioprio_set () | |
163 | returns 0. | |
164 | On error, \-1 is returned, and | |
165 | .I errno | |
166 | is set to indicate the error. | |
167 | .SH ERRORS | |
168 | .TP | |
eab64696 MK |
169 | .B EINVAL |
170 | Invalid value for | |
171 | .I which | |
172 | or | |
173 | .IR ioprio . | |
174 | Refer to the NOTES section for available scheduler | |
175 | classes and priority levels for | |
176 | .IR ioprio . | |
177 | .TP | |
5b3b2ce1 MK |
178 | .B EPERM |
179 | The calling process does not have the privilege needed to assign this | |
180 | .I ioprio | |
181 | to the specified process(es). | |
182 | See the NOTES section for more information on required | |
183 | privileges for | |
184 | .BR ioprio_set (). | |
185 | .TP | |
186 | .B ESRCH | |
187 | No process(es) could be found that matched the specification in | |
188 | .I which | |
189 | and | |
190 | .IR who . | |
a1d5f77c MK |
191 | .SH VERSIONS |
192 | These system calls have been available on Linux since | |
193 | kernel 2.6.13. | |
3113c7f3 | 194 | .SH STANDARDS |
8382f16d | 195 | These system calls are Linux-specific. |
5b3b2ce1 | 196 | .SH NOTES |
b91e4e72 CM |
197 | Two or more processes or threads can share an I/O context. |
198 | This will be the case when | |
199 | .BR clone (2) | |
200 | was called with the | |
201 | .B CLONE_IO | |
202 | flag. | |
203 | However, by default, the distinct threads of a process will | |
204 | .B not | |
205 | share the same I/O context. | |
206 | This means that if you want to change the I/O | |
207 | priority of all threads in a process, you may need to call | |
208 | .BR ioprio_set () | |
209 | on each of the threads. | |
210 | The thread ID that you would need for this operation | |
211 | is the one that is returned by | |
212 | .BR gettid (2) | |
213 | or | |
214 | .BR clone (2). | |
efeece04 | 215 | .PP |
33a0ccb2 | 216 | These system calls have an effect only when used |
5b3b2ce1 | 217 | in conjunction with an I/O scheduler that supports I/O priorities. |
a98bcd58 | 218 | As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing |
5b3b2ce1 | 219 | (CFQ) I/O scheduler. |
efeece04 | 220 | .PP |
02906043 MK |
221 | If no I/O scheduler has been set for a thread, |
222 | then by default the I/O priority will follow the CPU nice value | |
223 | .RB ( setpriority (2)). | |
224 | In Linux kernels before version 2.6.24, | |
225 | once an I/O priority had been set using | |
226 | .BR ioprio_set (), | |
227 | there was no way to reset the I/O scheduling behavior to the default. | |
228 | Since Linux 2.6.24, | |
229 | .\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550 | |
230 | specifying | |
231 | .I ioprio | |
232 | as 0 can be used to reset to the default I/O scheduling behavior. | |
73d8cece | 233 | .SS Selecting an I/O scheduler |
7e5d08eb | 234 | I/O schedulers are selected on a per-device basis via the special |
5b3b2ce1 MK |
235 | file |
236 | .IR /sys/block/<device>/queue/scheduler . | |
efeece04 | 237 | .PP |
5b3b2ce1 MK |
238 | One can view the current I/O scheduler via the |
239 | .I /sys | |
9ee4a2b6 | 240 | filesystem. |
5b3b2ce1 MK |
241 | For example, the following command |
242 | displays a list of all schedulers currently loaded in the kernel: | |
bdd915e2 MK |
243 | .PP |
244 | .in +4n | |
245 | .EX | |
8ebf2cfb | 246 | .RB "$" " cat /sys/block/sda/queue/scheduler" |
5b3b2ce1 | 247 | noop anticipatory deadline [cfq] |
bdd915e2 MK |
248 | .EE |
249 | .in | |
250 | .PP | |
5b3b2ce1 MK |
251 | The scheduler surrounded by brackets is the one actually |
252 | in use for the device | |
8ebf2cfb | 253 | .RI ( sda |
5b3b2ce1 MK |
254 | in the example). |
255 | Setting another scheduler is done by writing the name of the | |
256 | new scheduler to this file. | |
39b9794d | 257 | For example, the following command will set the |
5b3b2ce1 | 258 | scheduler for the |
8ebf2cfb | 259 | .I sda |
5b3b2ce1 MK |
260 | device to |
261 | .IR cfq : | |
bdd915e2 MK |
262 | .PP |
263 | .in +4n | |
264 | .EX | |
b43a3b30 | 265 | .RB "$" " su" |
5b3b2ce1 | 266 | Password: |
8ebf2cfb | 267 | .RB "#" " echo cfq > /sys/block/sda/queue/scheduler" |
bdd915e2 MK |
268 | .EE |
269 | .in | |
270 | .\" | |
73d8cece | 271 | .SS The Completely Fair Queuing (CFQ) I/O scheduler |
a311ffd0 | 272 | Since version 3 (also known as CFQ Time Sliced), CFQ implements |
5b3b2ce1 MK |
273 | I/O nice levels similar to those |
274 | of CPU scheduling. | |
a311ffd0 | 275 | These nice levels are grouped into three scheduling classes, |
5b3b2ce1 MK |
276 | each one containing one or more priority levels: |
277 | .TP | |
278 | .BR IOPRIO_CLASS_RT " (1)" | |
c13182ef MK |
279 | This is the real-time I/O class. |
280 | This scheduling class is given | |
5b3b2ce1 MK |
281 | higher priority than any other class: |
282 | processes from this class are | |
283 | given first access to the disk every time. | |
a311ffd0 | 284 | Thus, this I/O class needs to be used with some |
5b3b2ce1 MK |
285 | care: one I/O real-time process can starve the entire system. |
286 | Within the real-time class, | |
287 | there are 8 levels of class data (priority) that determine exactly | |
288 | how much time this process needs the disk for on each service. | |
289 | The highest real-time priority level is 0; the lowest is 7. | |
a311ffd0 | 290 | In the future, this might change to be more directly mappable to |
5b3b2ce1 MK |
291 | performance, by passing in a desired data rate instead. |
292 | .TP | |
293 | .BR IOPRIO_CLASS_BE " (2)" | |
294 | This is the best-effort scheduling class, | |
295 | which is the default for any process | |
296 | that hasn't set a specific I/O priority. | |
297 | The class data (priority) determines how much | |
298 | I/O bandwidth the process will get. | |
299 | Best-effort priority levels are analogous to CPU nice values | |
300 | (see | |
301 | .BR getpriority (2)). | |
302 | The priority level determines a priority relative | |
303 | to other processes in the best-effort scheduling class. | |
304 | Priority levels range from 0 (highest) to 7 (lowest). | |
305 | .TP | |
306 | .BR IOPRIO_CLASS_IDLE " (3)" | |
307 | This is the idle scheduling class. | |
2bf79fbd | 308 | Processes running at this level get I/O |
9b13f770 | 309 | time only when no one else needs the disk. |
d22faa34 | 310 | The idle class has no class data. |
39b9794d | 311 | Attention is required when assigning this priority class to a process, |
5b3b2ce1 MK |
312 | since it may become starved if higher priority processes are |
313 | constantly accessing the disk. | |
314 | .PP | |
4965810a | 315 | Refer to the kernel source file |
5b3b2ce1 MK |
316 | .I Documentation/block/ioprio.txt |
317 | for more information on the CFQ I/O Scheduler and an example program. | |
73d8cece | 318 | .SS Required permissions to set I/O priorities |
5b3b2ce1 | 319 | Permission to change a process's priority is granted or denied based |
a311ffd0 | 320 | on two criteria: |
5b3b2ce1 MK |
321 | .TP |
322 | .B "Process ownership" | |
a311ffd0 | 323 | An unprivileged process may set the I/O priority only for a process |
5b3b2ce1 MK |
324 | whose real UID |
325 | matches the real or effective UID of the calling process. | |
326 | A process which has the | |
327 | .B CAP_SYS_NICE | |
328 | capability can change the priority of any process. | |
329 | .TP | |
330 | .B "What is the desired priority" | |
331 | Attempts to set very high priorities | |
332 | .RB ( IOPRIO_CLASS_RT ) | |
5b3b2ce1 MK |
333 | require the |
334 | .B CAP_SYS_ADMIN | |
335 | capability. | |
d22faa34 MK |
336 | Kernel versions up to 2.6.24 also required |
337 | .B CAP_SYS_ADMIN | |
338 | to set a very low priority | |
339 | .RB ( IOPRIO_CLASS_IDLE ), | |
340 | but since Linux 2.6.25, this is no longer required. | |
5b3b2ce1 MK |
341 | .PP |
342 | A call to | |
343 | .BR ioprio_set () | |
344 | must follow both rules, or the call will fail with the error | |
345 | .BR EPERM . | |
346 | .SH BUGS | |
1a549f8c MK |
347 | .\" 6 May 07: Bug report raised: |
348 | .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464 | |
f17d72ad | 349 | .\" Ulrich Drepper replied that he wasn't going to add these |
08fcffef | 350 | .\" to glibc. |
5b3b2ce1 MK |
351 | Glibc does not yet provide a suitable header file defining |
352 | the function prototypes and macros described on this page. | |
353 | Suitable definitions can be found in | |
354 | .IR linux/ioprio.h . | |
47297adb | 355 | .SH SEE ALSO |
77a5d966 | 356 | .BR ionice (1), |
56d2079d | 357 | .BR getpriority (2), |
f09cbcf3 | 358 | .BR open (2), |
ae2ff8f9 MK |
359 | .BR capabilities (7), |
360 | .BR cgroups (7) | |
efeece04 | 361 | .PP |
173fe7e7 DP |
362 | .I Documentation/block/ioprio.txt |
363 | in the Linux kernel source tree |