1 .\" Copyright (c) International Business Machines orp., 2006
3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
4 .\" This program is free software; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
12 .\" the GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public
15 .\" License along with this manual; if not, see
16 .\" <http://www.gnu.org/licenses/>.
20 .\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com>
21 .\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com>
24 .TH IOPRIO_SET 2 2021-06-20 "Linux" "Linux Programmer's Manual"
26 ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
29 .BR "#include <linux/ioprio.h> " "/* Definition of " IOPRIO_* " constants */"
30 .BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */"
31 .B #include <unistd.h>
33 .BI "int syscall(SYS_ioprio_get, int " which ", int " who );
34 .BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio );
38 glibc provides no wrappers for these system calls,
39 necessitating the use of
46 system calls get and set the I/O scheduling class and
47 priority of one or more threads.
53 arguments identify the thread(s) on which the system
57 argument determines how
59 is interpreted, and has one of the following values:
63 is a process ID or thread ID identifying a single process or thread.
66 is 0, then operate on the calling thread.
70 is a process group ID identifying all the members of a process group.
73 is 0, then operate on the process group of which the caller is a member.
77 is a user ID identifying all of the processes that
78 have a matching real UID.
79 .\" FIXME . Need to document the behavior when 'who" is specified as 0
80 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
90 and more than one process matches
92 then the returned priority will be the highest one found among
93 all of the matching processes.
94 One priority is said to be
95 higher than another one if it belongs to a higher priority
98 is the highest priority class;
101 or if it belongs to the same priority class as the other process but
102 has a higher priority level (a lower priority number means a
103 higher priority level).
109 is a bit mask that specifies both the scheduling class and the
110 priority to be assigned to the target process(es).
111 The following macros are used for assembling and dissecting
115 .BI IOPRIO_PRIO_VALUE( class ", " data )
120 this macro combines the two values to produce an
122 value, which is returned as the result of the macro.
124 .BI IOPRIO_PRIO_CLASS( mask )
129 value), this macro returns its I/O class component, that is,
131 .BR IOPRIO_CLASS_RT ,
132 .BR IOPRIO_CLASS_BE ,
134 .BR IOPRIO_CLASS_IDLE .
136 .BI IOPRIO_PRIO_DATA( mask )
141 value), this macro returns its priority
145 See the NOTES section for more
146 information on scheduling classes and priorities,
147 as well as the meaning of specifying
151 I/O priorities are supported for reads and for synchronous
155 I/O priorities are not supported for asynchronous
156 writes because they are issued outside the context of the program
157 dirtying the memory, and thus program-specific priorities do not apply.
163 value of the process with highest I/O priority of any of the processes
164 that match the criteria specified in
168 On error, \-1 is returned, and
170 is set to indicate the error.
175 On error, \-1 is returned, and
177 is set to indicate the error.
185 Refer to the NOTES section for available scheduler
186 classes and priority levels for
190 The calling process does not have the privilege needed to assign this
192 to the specified process(es).
193 See the NOTES section for more information on required
198 No process(es) could be found that matched the specification in
203 These system calls have been available on Linux since
206 These system calls are Linux-specific.
208 Two or more processes or threads can share an I/O context.
209 This will be the case when
214 However, by default, the distinct threads of a process will
216 share the same I/O context.
217 This means that if you want to change the I/O
218 priority of all threads in a process, you may need to call
220 on each of the threads.
221 The thread ID that you would need for this operation
222 is the one that is returned by
227 These system calls have an effect only when used
228 in conjunction with an I/O scheduler that supports I/O priorities.
229 As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
232 If no I/O scheduler has been set for a thread,
233 then by default the I/O priority will follow the CPU nice value
234 .RB ( setpriority (2)).
235 In Linux kernels before version 2.6.24,
236 once an I/O priority had been set using
238 there was no way to reset the I/O scheduling behavior to the default.
240 .\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550
243 as 0 can be used to reset to the default I/O scheduling behavior.
244 .SS Selecting an I/O scheduler
245 I/O schedulers are selected on a per-device basis via the special
247 .IR /sys/block/<device>/queue/scheduler .
249 One can view the current I/O scheduler via the
252 For example, the following command
253 displays a list of all schedulers currently loaded in the kernel:
257 .RB "$" " cat /sys/block/sda/queue/scheduler"
258 noop anticipatory deadline [cfq]
262 The scheduler surrounded by brackets is the one actually
263 in use for the device
266 Setting another scheduler is done by writing the name of the
267 new scheduler to this file.
268 For example, the following command will set the
278 .RB "#" " echo cfq > /sys/block/sda/queue/scheduler"
282 .SS The Completely Fair Queuing (CFQ) I/O scheduler
283 Since version 3 (also known as CFQ Time Sliced), CFQ implements
284 I/O nice levels similar to those
286 These nice levels are grouped into three scheduling classes,
287 each one containing one or more priority levels:
289 .BR IOPRIO_CLASS_RT " (1)"
290 This is the real-time I/O class.
291 This scheduling class is given
292 higher priority than any other class:
293 processes from this class are
294 given first access to the disk every time.
295 Thus, this I/O class needs to be used with some
296 care: one I/O real-time process can starve the entire system.
297 Within the real-time class,
298 there are 8 levels of class data (priority) that determine exactly
299 how much time this process needs the disk for on each service.
300 The highest real-time priority level is 0; the lowest is 7.
301 In the future, this might change to be more directly mappable to
302 performance, by passing in a desired data rate instead.
304 .BR IOPRIO_CLASS_BE " (2)"
305 This is the best-effort scheduling class,
306 which is the default for any process
307 that hasn't set a specific I/O priority.
308 The class data (priority) determines how much
309 I/O bandwidth the process will get.
310 Best-effort priority levels are analogous to CPU nice values
312 .BR getpriority (2)).
313 The priority level determines a priority relative
314 to other processes in the best-effort scheduling class.
315 Priority levels range from 0 (highest) to 7 (lowest).
317 .BR IOPRIO_CLASS_IDLE " (3)"
318 This is the idle scheduling class.
319 Processes running at this level get I/O
320 time only when no one else needs the disk.
321 The idle class has no class data.
322 Attention is required when assigning this priority class to a process,
323 since it may become starved if higher priority processes are
324 constantly accessing the disk.
326 Refer to the kernel source file
327 .I Documentation/block/ioprio.txt
328 for more information on the CFQ I/O Scheduler and an example program.
329 .SS Required permissions to set I/O priorities
330 Permission to change a process's priority is granted or denied based
333 .B "Process ownership"
334 An unprivileged process may set the I/O priority only for a process
336 matches the real or effective UID of the calling process.
337 A process which has the
339 capability can change the priority of any process.
341 .B "What is the desired priority"
342 Attempts to set very high priorities
343 .RB ( IOPRIO_CLASS_RT )
347 Kernel versions up to 2.6.24 also required
349 to set a very low priority
350 .RB ( IOPRIO_CLASS_IDLE ),
351 but since Linux 2.6.25, this is no longer required.
355 must follow both rules, or the call will fail with the error
358 .\" 6 May 07: Bug report raised:
359 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
360 .\" Ulrich Drepper replied that he wasn't going to add these
362 Glibc does not yet provide a suitable header file defining
363 the function prototypes and macros described on this page.
364 Suitable definitions can be found in
370 .BR capabilities (7),
373 .I Documentation/block/ioprio.txt
374 in the Linux kernel source tree