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 2015-07-23 "Linux" "Linux Programmer's Manual"
26 ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
29 .BI "int ioprio_get(int " which ", int " who );
30 .BI "int ioprio_set(int " which ", int " who ", int " ioprio );
34 There are no glibc wrappers for these system calls; see NOTES.
40 system calls respectively get and set the I/O scheduling class and
41 priority of one or more threads.
47 arguments identify the thread(s) on which the system
51 argument determines how
53 is interpreted, and has one of the following values:
57 is a process ID or thread ID identifying a single process or thread.
60 is 0, then operate on the calling thread.
64 is a process group ID identifying all the members of a process group.
67 is 0, then operate on the process group of which the caller is a member.
71 is a user ID identifying all of the processes that
72 have a matching real UID.
73 .\" FIXME . Need to document the behavior when 'who" is specified as 0
74 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
84 and more than one process matches
86 then the returned priority will be the highest one found among
87 all of the matching processes.
88 One priority is said to be
89 higher than another one if it belongs to a higher priority
92 is the highest priority class;
95 or if it belongs to the same priority class as the other process but
96 has a higher priority level (a lower priority number means a
97 higher priority level).
103 is a bit mask that specifies both the scheduling class and the
104 priority to be assigned to the target process(es).
105 The following macros are used for assembling and dissecting
109 .BI IOPRIO_PRIO_VALUE( class ", " data )
114 this macro combines the two values to produce an
116 value, which is returned as the result of the macro.
118 .BI IOPRIO_PRIO_CLASS( mask )
123 value), this macro returns its I/O class component, that is,
125 .BR IOPRIO_CLASS_RT ,
126 .BR IOPRIO_CLASS_BE ,
128 .BR IOPRIO_CLASS_IDLE .
130 .BI IOPRIO_PRIO_DATA( mask )
135 value), this macro returns its priority
139 See the NOTES section for more
140 information on scheduling classes and priorities,
141 as well as the meaning of specifying
145 I/O priorities are supported for reads and for synchronous
149 I/O priorities are not supported for asynchronous
150 writes because they are issued outside the context of the program
151 dirtying the memory, and thus program-specific priorities do not apply.
157 value of the process with highest I/O priority of any of the processes
158 that match the criteria specified in
162 On error, \-1 is returned, and
164 is set to indicate the error.
169 On error, \-1 is returned, and
171 is set to indicate the error.
179 Refer to the NOTES section for available scheduler
180 classes and priority levels for
184 The calling process does not have the privilege needed to assign this
186 to the specified process(es).
187 See the NOTES section for more information on required
192 No process(es) could be found that matched the specification in
197 These system calls have been available on Linux since
200 These system calls are Linux-specific.
202 Glibc does not provide a wrapper for these system calls; call them using
205 Two or more processes or threads can share an I/O context.
206 This will be the case when
211 However, by default, the distinct threads of a process will
213 share the same I/O context.
214 This means that if you want to change the I/O
215 priority of all threads in a process, you may need to call
217 on each of the threads.
218 The thread ID that you would need for this operation
219 is the one that is returned by
224 These system calls have an effect only when used
225 in conjunction with an I/O scheduler that supports I/O priorities.
226 As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
229 If no I/O scheduler has been set for a thread,
230 then by default the I/O priority will follow the CPU nice value
231 .RB ( setpriority (2)).
232 In Linux kernels before version 2.6.24,
233 once an I/O priority had been set using
235 there was no way to reset the I/O scheduling behavior to the default.
237 .\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550
240 as 0 can be used to reset to the default I/O scheduling behavior.
241 .SS Selecting an I/O scheduler
242 I/O schedulers are selected on a per-device basis via the special
244 .IR /sys/block/<device>/queue/scheduler .
246 One can view the current I/O scheduler via the
249 For example, the following command
250 displays a list of all schedulers currently loaded in the kernel:
254 .RB "$" " cat /sys/block/sda/queue/scheduler"
255 noop anticipatory deadline [cfq]
259 The scheduler surrounded by brackets is the one actually
260 in use for the device
263 Setting another scheduler is done by writing the name of the
264 new scheduler to this file.
265 For example, the following command will set the
275 .RB "#" " echo cfq > /sys/block/sda/queue/scheduler"
278 .SS The Completely Fair Queuing (CFQ) I/O scheduler
279 Since version 3 (also known as CFQ Time Sliced), CFQ implements
280 I/O nice levels similar to those
282 These nice levels are grouped into three scheduling classes,
283 each one containing one or more priority levels:
285 .BR IOPRIO_CLASS_RT " (1)"
286 This is the real-time I/O class.
287 This scheduling class is given
288 higher priority than any other class:
289 processes from this class are
290 given first access to the disk every time.
291 Thus, this I/O class needs to be used with some
292 care: one I/O real-time process can starve the entire system.
293 Within the real-time class,
294 there are 8 levels of class data (priority) that determine exactly
295 how much time this process needs the disk for on each service.
296 The highest real-time priority level is 0; the lowest is 7.
297 In the future, this might change to be more directly mappable to
298 performance, by passing in a desired data rate instead.
300 .BR IOPRIO_CLASS_BE " (2)"
301 This is the best-effort scheduling class,
302 which is the default for any process
303 that hasn't set a specific I/O priority.
304 The class data (priority) determines how much
305 I/O bandwidth the process will get.
306 Best-effort priority levels are analogous to CPU nice values
308 .BR getpriority (2)).
309 The priority level determines a priority relative
310 to other processes in the best-effort scheduling class.
311 Priority levels range from 0 (highest) to 7 (lowest).
313 .BR IOPRIO_CLASS_IDLE " (3)"
314 This is the idle scheduling class.
315 Processes running at this level get I/O
316 time only when no-one else needs the disk.
317 The idle class has no class data.
318 Attention is required when assigning this priority class to a process,
319 since it may become starved if higher priority processes are
320 constantly accessing the disk.
322 Refer to the kernel source file
323 .I Documentation/block/ioprio.txt
324 for more information on the CFQ I/O Scheduler and an example program.
325 .SS Required permissions to set I/O priorities
326 Permission to change a process's priority is granted or denied based
329 .B "Process ownership"
330 An unprivileged process may set the I/O priority only for a process
332 matches the real or effective UID of the calling process.
333 A process which has the
335 capability can change the priority of any process.
337 .B "What is the desired priority"
338 Attempts to set very high priorities
339 .RB ( IOPRIO_CLASS_RT )
343 Kernel versions up to 2.6.24 also required
345 to set a very low priority
346 .RB ( IOPRIO_CLASS_IDLE ),
347 but since Linux 2.6.25, this is no longer required.
351 must follow both rules, or the call will fail with the error
354 .\" 6 May 07: Bug report raised:
355 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
356 .\" Ulrich Drepper replied that he wasn't going to add these
358 Glibc does not yet provide a suitable header file defining
359 the function prototypes and macros described on this page.
360 Suitable definitions can be found in
366 .BR capabilities (7),
369 .I Documentation/block/ioprio.txt
370 in the Linux kernel source tree