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 2013-02-12 "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 who==0 needs to be documented,
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.
142 I/O priorities are supported for reads and for synchronous
146 I/O priorities are not supported for asynchronous
147 writes because they are issued outside the context of the program
148 dirtying the memory, and thus program-specific priorities do not apply.
154 value of the process with highest I/O priority of any of the processes
155 that match the criteria specified in
159 On error, \-1 is returned, and
161 is set to indicate the error.
166 On error, \-1 is returned, and
168 is set to indicate the error.
176 Refer to the NOTES section for available scheduler
177 classes and priority levels for
181 The calling process does not have the privilege needed to assign this
183 to the specified process(es).
184 See the NOTES section for more information on required
189 No process(es) could be found that matched the specification in
194 These system calls have been available on Linux since
197 These system calls are Linux-specific.
199 Glibc does not provide a wrapper for these system calls; call them using
202 Two or more processes or threads can share an I/O context.
203 This will be the case when
208 However, by default, the distinct threads of a process will
210 share the same I/O context.
211 This means that if you want to change the I/O
212 priority of all threads in a process, you may need to call
214 on each of the threads.
215 The thread ID that you would need for this operation
216 is the one that is returned by
221 These system calls only have an effect when used
222 in conjunction with an I/O scheduler that supports I/O priorities.
223 As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
225 .SS Selecting an I/O scheduler
226 I/O Schedulers are selected on a per-device basis via the special
228 .IR /sys/block/<device>/queue/scheduler .
230 One can view the current I/O scheduler via the
233 For example, the following command
234 displays a list of all schedulers currently loaded in the kernel:
238 .RB "$" " cat /sys/block/hda/queue/scheduler"
239 noop anticipatory deadline [cfq]
243 The scheduler surrounded by brackets is the one actually
244 in use for the device
247 Setting another scheduler is done by writing the name of the
248 new scheduler to this file.
249 For example, the following command will set the
259 .RB "#" " echo cfq > /sys/block/hda/queue/scheduler"
262 .SS The Completely Fair Queuing (CFQ) I/O scheduler
263 Since v3 (aka CFQ Time Sliced) CFQ implements
264 I/O nice levels similar to those
266 These nice levels are grouped in three scheduling classes
267 each one containing one or more priority levels:
269 .BR IOPRIO_CLASS_RT " (1)"
270 This is the real-time I/O class.
271 This scheduling class is given
272 higher priority than any other class:
273 processes from this class are
274 given first access to the disk every time.
275 Thus this I/O class needs to be used with some
276 care: one I/O real-time process can starve the entire system.
277 Within the real-time class,
278 there are 8 levels of class data (priority) that determine exactly
279 how much time this process needs the disk for on each service.
280 The highest real-time priority level is 0; the lowest is 7.
281 In the future this might change to be more directly mappable to
282 performance, by passing in a desired data rate instead.
284 .BR IOPRIO_CLASS_BE " (2)"
285 This is the best-effort scheduling class,
286 which is the default for any process
287 that hasn't set a specific I/O priority.
288 The class data (priority) determines how much
289 I/O bandwidth the process will get.
290 Best-effort priority levels are analogous to CPU nice values
292 .BR getpriority (2)).
293 The priority level determines a priority relative
294 to other processes in the best-effort scheduling class.
295 Priority levels range from 0 (highest) to 7 (lowest).
297 .BR IOPRIO_CLASS_IDLE " (3)"
298 This is the idle scheduling class.
299 Processes running at this level only get I/O
300 time when no-one else needs the disk.
301 The idle class has no class data.
302 Attention is required when assigning this priority class to a process,
303 since it may become starved if higher priority processes are
304 constantly accessing the disk.
307 .I Documentation/block/ioprio.txt
308 for more information on the CFQ I/O Scheduler and an example program.
309 .SS Required permissions to set I/O priorities
310 Permission to change a process's priority is granted or denied based
313 .B "Process ownership"
314 An unprivileged process may only set the I/O priority of a process
316 matches the real or effective UID of the calling process.
317 A process which has the
319 capability can change the priority of any process.
321 .B "What is the desired priority"
322 Attempts to set very high priorities
323 .RB ( IOPRIO_CLASS_RT )
327 Kernel versions up to 2.6.24 also required
329 to set a very low priority
330 .RB ( IOPRIO_CLASS_IDLE ),
331 but since Linux 2.6.25, this is no longer required.
335 must follow both rules, or the call will fail with the error
338 .\" 6 May 07: Bug report raised:
339 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
340 .\" Ulrich Drepper replied that he wasn't going to add these
342 Glibc does not yet provide a suitable header file defining
343 the function prototypes and macros described on this page.
344 Suitable definitions can be found in
352 .I Documentation/block/ioprio.txt
353 in the Linux kernel source tree