]>
Commit | Line | Data |
---|---|---|
5b3b2ce1 MK |
1 | .\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :) |
2 | .\" | |
a98bcd58 | 3 | .\" Copyright (c) International Business Machines orp., 2006 |
5b3b2ce1 | 4 | .\" |
a98bcd58 | 5 | .\" This program is free software; you can redistribute it and/or |
5b3b2ce1 MK |
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. | |
9 | .\" | |
10 | .\" This program is distributed in the hope that it will be useful, | |
a98bcd58 MK |
11 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See | |
5b3b2ce1 MK |
13 | .\" the GNU General Public License for more details. |
14 | .\" | |
15 | .\" You should have received a copy of the GNU General Public License | |
a98bcd58 | 16 | .\" along with this program; if not, write to the Free Software |
5b3b2ce1 MK |
17 | .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
18 | .\" MA 02111-1307 USA | |
19 | .\" | |
20 | .\" HISTORY: | |
21 | .\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com> | |
c11b1abf | 22 | .\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com> |
5b3b2ce1 | 23 | .\" |
5b3b2ce1 | 24 | .\" |
527ea912 | 25 | .TH IOPRIO_SET 2 2007-06-01 "Linux" "Linux Programmer's Manual" |
5b3b2ce1 MK |
26 | .SH NAME |
27 | ioprio_get, ioprio_set \- get/set I/O scheduling class and priority | |
28 | .SH SYNOPSIS | |
29 | .nf | |
5b3b2ce1 MK |
30 | .BI "int ioprio_get(int " which ", int " who ); |
31 | .BI "int ioprio_set(int " which ", int " who ", int " ioprio ); | |
32 | .fi | |
33 | .SH DESCRIPTION | |
34 | The | |
35 | .BR ioprio_get () | |
36 | and | |
37 | .BR ioprio_set () | |
38 | system calls respectively get and set the I/O scheduling class and | |
39 | priority of one or more processes. | |
40 | ||
41 | The | |
42 | .I which | |
43 | and | |
44 | .I who | |
45 | arguments identify the process(es) on which the system | |
46 | calls operate. | |
47 | The | |
48 | .I which | |
49 | argument determines how | |
50 | .I who | |
51 | is interpreted, and has one of the following values: | |
52 | .TP | |
53 | .B IOPRIO_WHO_PROCESS | |
54 | .I who | |
55 | is a process ID identifying a single process. | |
56 | .TP | |
57 | .B IOPRIO_WHO_PGRP | |
58 | .I who | |
59 | is a process group ID identifying all the members of a process group. | |
60 | .TP | |
61 | .B IOPRIO_WHO_USER | |
62 | .I who | |
63 | is a user ID identifying all of the processes that | |
64 | have a matching real UID. | |
65 | .PP | |
66 | If | |
9606a1f3 | 67 | .I which |
5b3b2ce1 MK |
68 | is specified as |
69 | .B IOPRIO_WHO_PGRP | |
70 | or | |
71 | .B IOPRIO_WHO_USER | |
72 | when calling | |
73 | .BR ioprio_get (), | |
74 | and more than one process matches | |
75 | .IR who , | |
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 | |
80 | class | |
81 | .RB ( IOPRIO_CLASS_RT | |
82 | is the highest priority class; | |
83 | .B IOPRIO_CLASS_IDLE | |
84 | is the lowest) | |
85 | or if it belongs to the same priority class as the other process but | |
a98bcd58 | 86 | has a higher priority level (a lower priority number means a |
5b3b2ce1 MK |
87 | higher priority level). |
88 | ||
89 | The | |
90 | .I ioprio | |
91 | argument given to | |
92 | .BR ioprio_set () | |
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 | |
96 | .I ioprio | |
97 | values: | |
98 | .TP | |
99 | .BI IOPRIO_PRIO_VALUE( class ", " data ) | |
100 | Given a scheduling | |
101 | .I class | |
102 | and priority | |
103 | .RI ( data ), | |
104 | this macro combines the two values to produce an | |
105 | .I ioprio | |
106 | value, which is returned as the result of the macro. | |
107 | .TP | |
108 | .BI IOPRIO_PRIO_CLASS( mask ) | |
109 | Given | |
0daa9e92 | 110 | .I mask |
5b3b2ce1 | 111 | (an |
0daa9e92 | 112 | .I ioprio |
5b3b2ce1 MK |
113 | value), this macro returns its I/O class component, that is, |
114 | one of the values | |
115 | .BR IOPRIO_CLASS_RT , | |
116 | .BR IOPRIO_CLASS_BE , | |
117 | or | |
118 | .BR IOPRIO_CLASS_IDLE . | |
119 | .TP | |
120 | .BI IOPRIO_PRIO_DATA( mask ) | |
121 | Given | |
0daa9e92 | 122 | .I mask |
5b3b2ce1 | 123 | (an |
0daa9e92 | 124 | .I ioprio |
5b3b2ce1 MK |
125 | value), this macro returns its priority |
126 | .RI ( data ) | |
127 | component. | |
128 | .PP | |
129 | See the NOTES section for more | |
130 | information on scheduling classes and priorities. | |
a98bcd58 | 131 | |
682edefb MK |
132 | I/O priorities are supported for reads and for synchronous |
133 | .RB ( O_DIRECT , | |
134 | .BR O_SYNC ) | |
135 | writes. | |
c13182ef | 136 | I/O priorities are not supported for asynchronous |
a98bcd58 MK |
137 | writes because they are issued outside the context of the program |
138 | dirtying the memory, and thus program-specific priorities do not apply. | |
5b3b2ce1 MK |
139 | .SH "RETURN VALUE" |
140 | On success, | |
141 | .BR ioprio_get () | |
142 | returns the | |
143 | .I ioprio | |
144 | value of the process with highest I/O priority of any of the processes | |
145 | that match the criteria specified in | |
146 | .I which | |
147 | and | |
148 | .IR who . | |
149 | On error, \-1 is returned, and | |
150 | .I errno | |
151 | is set to indicate the error. | |
152 | .PP | |
153 | On success, | |
154 | .BR ioprio_set () | |
155 | returns 0. | |
156 | On error, \-1 is returned, and | |
157 | .I errno | |
158 | is set to indicate the error. | |
159 | .SH ERRORS | |
160 | .TP | |
eab64696 MK |
161 | .B EINVAL |
162 | Invalid value for | |
163 | .I which | |
164 | or | |
165 | .IR ioprio . | |
166 | Refer to the NOTES section for available scheduler | |
167 | classes and priority levels for | |
168 | .IR ioprio . | |
169 | .TP | |
5b3b2ce1 MK |
170 | .B EPERM |
171 | The calling process does not have the privilege needed to assign this | |
172 | .I ioprio | |
173 | to the specified process(es). | |
174 | See the NOTES section for more information on required | |
175 | privileges for | |
176 | .BR ioprio_set (). | |
177 | .TP | |
178 | .B ESRCH | |
179 | No process(es) could be found that matched the specification in | |
180 | .I which | |
181 | and | |
182 | .IR who . | |
a1d5f77c MK |
183 | .SH VERSIONS |
184 | These system calls have been available on Linux since | |
185 | kernel 2.6.13. | |
186 | .SH "CONFORMING TO" | |
8382f16d | 187 | These system calls are Linux-specific. |
5b3b2ce1 | 188 | .SH NOTES |
c12fd10d MK |
189 | Glibc does not provide wrapper for these system calls; call them using |
190 | .BR syscall (2). | |
191 | ||
5b3b2ce1 MK |
192 | These system calls only have an effect when used |
193 | in conjunction with an I/O scheduler that supports I/O priorities. | |
a98bcd58 | 194 | As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing |
5b3b2ce1 MK |
195 | (CFQ) I/O scheduler. |
196 | .SS "Selecting an I/O Scheduler" | |
197 | I/O Schedulers are selected on a per-device basis via the special | |
198 | file | |
199 | .IR /sys/block/<device>/queue/scheduler . | |
200 | ||
201 | One can view the current I/O scheduler via the | |
202 | .I /sys | |
203 | file system. | |
204 | For example, the following command | |
205 | displays a list of all schedulers currently loaded in the kernel: | |
206 | .sp | |
207 | .RS | |
208 | .nf | |
209 | $ cat /sys/block/hda/queue/scheduler | |
210 | noop anticipatory deadline [cfq] | |
211 | .fi | |
212 | .RE | |
213 | .sp | |
214 | The scheduler surrounded by brackets is the one actually | |
215 | in use for the device | |
216 | .RI ( hda | |
217 | in the example). | |
218 | Setting another scheduler is done by writing the name of the | |
219 | new scheduler to this file. | |
39b9794d | 220 | For example, the following command will set the |
5b3b2ce1 MK |
221 | scheduler for the |
222 | .I hda | |
223 | device to | |
224 | .IR cfq : | |
225 | .sp | |
226 | .RS | |
227 | .nf | |
228 | $ su | |
229 | Password: | |
230 | # echo cfq > /sys/block/hda/queue/scheduler | |
231 | .fi | |
232 | .RE | |
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 | |
236 | of CPU scheduling. | |
237 | These nice levels are grouped in three scheduling classes | |
238 | each one containing one or more priority levels: | |
239 | .TP | |
240 | .BR IOPRIO_CLASS_RT " (1)" | |
c13182ef MK |
241 | This is the real-time I/O class. |
242 | This scheduling class is given | |
5b3b2ce1 MK |
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. | |
254 | .TP | |
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 | |
262 | (see | |
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). | |
267 | .TP | |
268 | .BR IOPRIO_CLASS_IDLE " (3)" | |
269 | This is the idle scheduling class. | |
270 | Processes running at this level only get I/O | |
c13182ef MK |
271 | time when no one else needs the disk. |
272 | The idle class has no class | |
273 | data. | |
39b9794d | 274 | Attention is required when assigning this priority class to a process, |
5b3b2ce1 MK |
275 | since it may become starved if higher priority processes are |
276 | constantly accessing the disk. | |
277 | .PP | |
278 | Refer to | |
279 | .I Documentation/block/ioprio.txt | |
280 | for more information on the CFQ I/O Scheduler and an example program. | |
281 | .SS "Required permissions to set I/O priorities" | |
282 | Permission to change a process's priority is granted or denied based | |
283 | on two assertions: | |
284 | .TP | |
285 | .B "Process ownership" | |
286 | An unprivileged process may only set the I/O priority of a process | |
287 | whose real UID | |
288 | matches the real or effective UID of the calling process. | |
289 | A process which has the | |
290 | .B CAP_SYS_NICE | |
291 | capability can change the priority of any process. | |
292 | .TP | |
293 | .B "What is the desired priority" | |
294 | Attempts to set very high priorities | |
295 | .RB ( IOPRIO_CLASS_RT ) | |
296 | or very low ones | |
297 | .RB ( IOPRIO_CLASS_IDLE ) | |
298 | require the | |
299 | .B CAP_SYS_ADMIN | |
300 | capability. | |
301 | .PP | |
302 | A call to | |
303 | .BR ioprio_set () | |
304 | must follow both rules, or the call will fail with the error | |
305 | .BR EPERM . | |
306 | .SH BUGS | |
1a549f8c MK |
307 | .\" 6 May 07: Bug report raised: |
308 | .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464 | |
08fcffef MK |
309 | .\" Ulriich Drepper replied that he wasn't going to add these |
310 | .\" to glibc. | |
5b3b2ce1 MK |
311 | Glibc does not yet provide a suitable header file defining |
312 | the function prototypes and macros described on this page. | |
313 | Suitable definitions can be found in | |
314 | .IR linux/ioprio.h . | |
5b3b2ce1 | 315 | .SH "SEE ALSO" |
a98bcd58 | 316 | .BR getpriority "(2), " open "(2), " capabilities (7) |
5b3b2ce1 MK |
317 | .sp |
318 | Documentation/block/ioprio.txt in the kernel source tree. |