1 .\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
3 .\" Copyright (c) International Business Machines orp., 2006
5 .\" This program is free software; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License as
7 .\" published by the Free Software Foundation; either version 2 of
8 .\" the License, or (at your option) any later version.
10 .\" This program is distributed in the hope that it will be useful,
11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
13 .\" the GNU General Public License for more details.
15 .\" You should have received a copy of the GNU General Public License
16 .\" along with this program; if not, write to the Free Software
17 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
21 .\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com>
22 .\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com>
25 .TH IOPRIO_SET 2 2008-07-09 "Linux" "Linux Programmer's Manual"
27 ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
30 .BI "int ioprio_get(int " which ", int " who );
31 .BI "int ioprio_set(int " which ", int " who ", int " ioprio );
38 system calls respectively get and set the I/O scheduling class and
39 priority of one or more processes.
45 arguments identify the process(es) on which the system
49 argument determines how
51 is interpreted, and has one of the following values:
55 is a process ID identifying a single process.
59 is a process group ID identifying all the members of a process group.
63 is a user ID identifying all of the processes that
64 have a matching real UID.
74 and more than one process matches
76 then the returned priority will be the highest one found among
77 all of the matching processes.
78 One priority is said to be
79 higher than another one if it belongs to a higher priority
82 is the highest priority class;
85 or if it belongs to the same priority class as the other process but
86 has a higher priority level (a lower priority number means a
87 higher priority level).
93 is a bit mask that specifies both the scheduling class and the
94 priority to be assigned to the target process(es).
95 The following macros are used for assembling and dissecting
99 .BI IOPRIO_PRIO_VALUE( class ", " data )
104 this macro combines the two values to produce an
106 value, which is returned as the result of the macro.
108 .BI IOPRIO_PRIO_CLASS( mask )
113 value), this macro returns its I/O class component, that is,
115 .BR IOPRIO_CLASS_RT ,
116 .BR IOPRIO_CLASS_BE ,
118 .BR IOPRIO_CLASS_IDLE .
120 .BI IOPRIO_PRIO_DATA( mask )
125 value), this macro returns its priority
129 See the NOTES section for more
130 information on scheduling classes and priorities.
132 I/O priorities are supported for reads and for synchronous
136 I/O priorities are not supported for asynchronous
137 writes because they are issued outside the context of the program
138 dirtying the memory, and thus program-specific priorities do not apply.
144 value of the process with highest I/O priority of any of the processes
145 that match the criteria specified in
149 On error, \-1 is returned, and
151 is set to indicate the error.
156 On error, \-1 is returned, and
158 is set to indicate the error.
166 Refer to the NOTES section for available scheduler
167 classes and priority levels for
171 The calling process does not have the privilege needed to assign this
173 to the specified process(es).
174 See the NOTES section for more information on required
179 No process(es) could be found that matched the specification in
184 These system calls have been available on Linux since
187 These system calls are Linux-specific.
189 Glibc does not provide wrapper for these system calls; call them using
192 These system calls only have an effect when used
193 in conjunction with an I/O scheduler that supports I/O priorities.
194 As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
196 .SS "Selecting an I/O Scheduler"
197 I/O Schedulers are selected on a per-device basis via the special
199 .IR /sys/block/<device>/queue/scheduler .
201 One can view the current I/O scheduler via the
204 For example, the following command
205 displays a list of all schedulers currently loaded in the kernel:
209 $ cat /sys/block/hda/queue/scheduler
210 noop anticipatory deadline [cfq]
214 The scheduler surrounded by brackets is the one actually
215 in use for the device
218 Setting another scheduler is done by writing the name of the
219 new scheduler to this file.
220 For example, the following command will set the
230 # echo cfq > /sys/block/hda/queue/scheduler
233 .SS "The Completely Fair Queuing (CFQ) I/O Scheduler"
234 Since v3 (aka CFQ Time Sliced) CFQ implements
235 I/O nice levels similar to those
237 These nice levels are grouped in three scheduling classes
238 each one containing one or more priority levels:
240 .BR IOPRIO_CLASS_RT " (1)"
241 This is the real-time I/O class.
242 This scheduling class is given
243 higher priority than any other class:
244 processes from this class are
245 given first access to the disk every time.
246 Thus this I/O class needs to be used with some
247 care: one I/O real-time process can starve the entire system.
248 Within the real-time class,
249 there are 8 levels of class data (priority) that determine exactly
250 how much time this process needs the disk for on each service.
251 The highest real-time priority level is 0; the lowest is 7.
252 In the future this might change to be more directly mappable to
253 performance, by passing in a desired data rate instead.
255 .BR IOPRIO_CLASS_BE " (2)"
256 This is the best-effort scheduling class,
257 which is the default for any process
258 that hasn't set a specific I/O priority.
259 The class data (priority) determines how much
260 I/O bandwidth the process will get.
261 Best-effort priority levels are analogous to CPU nice values
263 .BR getpriority (2)).
264 The priority level determines a priority relative
265 to other processes in the best-effort scheduling class.
266 Priority levels range from 0 (highest) to 7 (lowest).
268 .BR IOPRIO_CLASS_IDLE " (3)"
269 This is the idle scheduling class.
270 Processes running at this level only get I/O
271 time when no-one else needs the disk.
272 The idle class has no class data.
273 Attention is required when assigning this priority class to a process,
274 since it may become starved if higher priority processes are
275 constantly accessing the disk.
278 .I Documentation/block/ioprio.txt
279 for more information on the CFQ I/O Scheduler and an example program.
280 .SS "Required permissions to set I/O priorities"
281 Permission to change a process's priority is granted or denied based
284 .B "Process ownership"
285 An unprivileged process may only set the I/O priority of a process
287 matches the real or effective UID of the calling process.
288 A process which has the
290 capability can change the priority of any process.
292 .B "What is the desired priority"
293 Attempts to set very high priorities
294 .RB ( IOPRIO_CLASS_RT )
298 Kernel versions up to 2.6.24 also required
300 to set a very low priority
301 .RB ( IOPRIO_CLASS_IDLE ),
302 but since Linux 2.6.25, this is no longer required.
306 must follow both rules, or the call will fail with the error
309 .\" 6 May 07: Bug report raised:
310 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
311 .\" Ulriich Drepper replied that he wasn't going to add these
313 Glibc does not yet provide a suitable header file defining
314 the function prototypes and macros described on this page.
315 Suitable definitions can be found in
318 .BR getpriority "(2), " open "(2), " capabilities (7)
320 Documentation/block/ioprio.txt in the kernel source tree.