Debian Codegraph @

upstream/debian-unstable/man2/ioprio_set.2

raw
1 .\" Copyright 2006, International Business Machines Corp.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH ioprio_set 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/ioprio.h> " "/* Definition of " IOPRIO_* " constants */"
15 .BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_ioprio_get, int " which ", int " who );
19 .BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio );
20 .fi
21 .P
22 .IR Note :
23 glibc provides no wrappers for these system calls,
24 necessitating the use of
25 .BR syscall (2).
26 .SH DESCRIPTION
27 The
28 .BR ioprio_get ()
29 and
30 .BR ioprio_set ()
31 system calls get and set the I/O scheduling class and
32 priority of one or more threads.
33 .P
34 The
35 .I which
36 and
37 .I who
38 arguments identify the thread(s) on which the system
39 calls operate.
40 The
41 .I which
42 argument determines how
43 .I who
44 is interpreted, and has one of the following values:
45 .TP
46 .B IOPRIO_WHO_PROCESS
47 .I who
48 is a process ID or thread ID identifying a single process or thread.
49 If
50 .I who
51 is 0, then operate on the calling thread.
52 .TP
53 .B IOPRIO_WHO_PGRP
54 .I who
55 is a process group ID identifying all the members of a process group.
56 If
57 .I who
58 is 0, then operate on the process group of which the caller is a member.
59 .TP
60 .B IOPRIO_WHO_USER
61 .I who
62 is a user ID identifying all of the processes that
63 have a matching real UID.
64 .\" FIXME . Need to document the behavior when 'who" is specified as 0
65 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
66 .P
67 If
68 .I which
69 is specified as
70 .B IOPRIO_WHO_PGRP
71 or
72 .B IOPRIO_WHO_USER
73 when calling
74 .BR ioprio_get (),
75 and more than one process matches
76 .IR who ,
77 then the returned priority will be the highest one found among
78 all of the matching processes.
79 One priority is said to be
80 higher than another one if it belongs to a higher priority
81 class
82 .RB ( IOPRIO_CLASS_RT
83 is the highest priority class;
84 .B IOPRIO_CLASS_IDLE
85 is the lowest)
86 or if it belongs to the same priority class as the other process but
87 has a higher priority level (a lower priority number means a
88 higher priority level).
89 .P
90 The
91 .I ioprio
92 argument given to
93 .BR ioprio_set ()
94 is a bit mask that specifies both the scheduling class and the
95 priority to be assigned to the target process(es).
96 The following macros are used for assembling and dissecting
97 .I ioprio
98 values:
99 .TP
100 .BI IOPRIO_PRIO_VALUE( class ", " data )
101 Given a scheduling
102 .I class
103 and priority
104 .RI ( data ),
105 this macro combines the two values to produce an
106 .I ioprio
107 value, which is returned as the result of the macro.
108 .TP
109 .BI IOPRIO_PRIO_CLASS( mask )
110 Given
111 .I mask
112 (an
113 .I ioprio
114 value), this macro returns its I/O class component, that is,
115 one of the values
116 .BR IOPRIO_CLASS_RT ,
117 .BR IOPRIO_CLASS_BE ,
118 or
119 .BR IOPRIO_CLASS_IDLE .
120 .TP
121 .BI IOPRIO_PRIO_DATA( mask )
122 Given
123 .I mask
124 (an
125 .I ioprio
126 value), this macro returns its priority
127 .RI ( data )
128 component.
129 .P
130 See the NOTES section for more
131 information on scheduling classes and priorities,
132 as well as the meaning of specifying
133 .I ioprio
134 as 0.
135 .P
136 I/O priorities are supported for reads and for synchronous
137 .RB ( O_DIRECT ,
138 .BR O_SYNC )
139 writes.
140 I/O priorities are not supported for asynchronous
141 writes because they are issued outside the context of the program
142 dirtying the memory, and thus program-specific priorities do not apply.
143 .SH RETURN VALUE
144 On success,
145 .BR ioprio_get ()
146 returns the
147 .I ioprio
148 value of the process with highest I/O priority of any of the processes
149 that match the criteria specified in
150 .I which
151 and
152 .IR who .
153 On error, \-1 is returned, and
154 .I errno
155 is set to indicate the error.
156 .P
157 On success,
158 .BR ioprio_set ()
159 returns 0.
160 On error, \-1 is returned, and
161 .I errno
162 is set to indicate the error.
163 .SH ERRORS
164 .TP
165 .B EINVAL
166 Invalid value for
167 .I which
168 or
169 .IR ioprio .
170 Refer to the NOTES section for available scheduler
171 classes and priority levels for
172 .IR ioprio .
173 .TP
174 .B EPERM
175 The calling process does not have the privilege needed to assign this
176 .I ioprio
177 to the specified process(es).
178 See the NOTES section for more information on required
179 privileges for
180 .BR ioprio_set ().
181 .TP
182 .B ESRCH
183 No process(es) could be found that matched the specification in
184 .I which
185 and
186 .IR who .
187 .SH STANDARDS
188 Linux.
189 .SH HISTORY
190 Linux 2.6.13.
191 .SH NOTES
192 Two or more processes or threads can share an I/O context.
193 This will be the case when
194 .BR clone (2)
195 was called with the
196 .B CLONE_IO
197 flag.
198 However, by default, the distinct threads of a process will
199 .B not
200 share the same I/O context.
201 This means that if you want to change the I/O
202 priority of all threads in a process, you may need to call
203 .BR ioprio_set ()
204 on each of the threads.
205 The thread ID that you would need for this operation
206 is the one that is returned by
207 .BR gettid (2)
208 or
209 .BR clone (2).
210 .P
211 These system calls have an effect only when used
212 in conjunction with an I/O scheduler that supports I/O priorities.
213 As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
214 (CFQ) I/O scheduler.
215 .P
216 If no I/O scheduler has been set for a thread,
217 then by default the I/O priority will follow the CPU nice value
218 .RB ( setpriority (2)).
219 Before Linux 2.6.24,
220 once an I/O priority had been set using
221 .BR ioprio_set (),
222 there was no way to reset the I/O scheduling behavior to the default.
223 Since Linux 2.6.24,
224 .\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550
225 specifying
226 .I ioprio
227 as 0 can be used to reset to the default I/O scheduling behavior.
228 .SS Selecting an I/O scheduler
229 I/O schedulers are selected on a per-device basis via the special
230 file
231 .IR /sys/block/ device /queue/scheduler .
232 .P
233 One can view the current I/O scheduler via the
234 .I /sys
235 filesystem.
236 For example, the following command
237 displays a list of all schedulers currently loaded in the kernel:
238 .P
239 .in +4n
240 .EX
241 .RB "$" " cat /sys/block/sda/queue/scheduler"
242 noop anticipatory deadline [cfq]
243 .EE
244 .in
245 .P
246 The scheduler surrounded by brackets is the one actually
247 in use for the device
248 .RI ( sda
249 in the example).
250 Setting another scheduler is done by writing the name of the
251 new scheduler to this file.
252 For example, the following command will set the
253 scheduler for the
254 .I sda
255 device to
256 .IR cfq :
257 .P
258 .in +4n
259 .EX
260 .RB "$" " su"
261 Password:
262 .RB "#" " echo cfq > /sys/block/sda/queue/scheduler"
263 .EE
264 .in
265 .\"
266 .SS The Completely Fair Queuing (CFQ) I/O scheduler
267 Since version 3 (also known as CFQ Time Sliced), CFQ implements
268 I/O nice levels similar to those
269 of CPU scheduling.
270 These nice levels are grouped into three scheduling classes,
271 each one containing one or more priority levels:
272 .TP
273 .BR IOPRIO_CLASS_RT " (1)"
274 This is the real-time I/O class.
275 This scheduling class is given
276 higher priority than any other class:
277 processes from this class are
278 given first access to the disk every time.
279 Thus, this I/O class needs to be used with some
280 care: one I/O real-time process can starve the entire system.
281 Within the real-time class,
282 there are 8 levels of class data (priority) that determine exactly
283 how much time this process needs the disk for on each service.
284 The highest real-time priority level is 0;
285 the lowest is 7.
286 In the future, this might change to be more directly mappable to
287 performance, by passing in a desired data rate instead.
288 .TP
289 .BR IOPRIO_CLASS_BE " (2)"
290 This is the best-effort scheduling class,
291 which is the default for any process
292 that hasn't set a specific I/O priority.
293 The class data (priority) determines how much
294 I/O bandwidth the process will get.
295 Best-effort priority levels are analogous to CPU nice values
296 (see
297 .BR getpriority (2)).
298 The priority level determines a priority relative
299 to other processes in the best-effort scheduling class.
300 Priority levels range from 0 (highest) to 7 (lowest).
301 .TP
302 .BR IOPRIO_CLASS_IDLE " (3)"
303 This is the idle scheduling class.
304 Processes running at this level get I/O
305 time only when no one else needs the disk.
306 The idle class has no class data.
307 Attention is required when assigning this priority class to a process,
308 since it may become starved if higher priority processes are
309 constantly accessing the disk.
310 .P
311 Refer to the kernel source file
312 .I Documentation/block/ioprio.rst
313 for more information on the CFQ I/O Scheduler and an example program.
314 .SS Required permissions to set I/O priorities
315 Permission to change a process's priority is granted or denied based
316 on two criteria:
317 .TP
318 .B "Process ownership"
319 An unprivileged process may set the I/O priority only for a process
320 whose real UID
321 matches the real or effective UID of the calling process.
322 A process which has the
323 .B CAP_SYS_NICE
324 capability can change the priority of any process.
325 .TP
326 .B "What is the desired priority"
327 Attempts to set very high priorities
328 .RB ( IOPRIO_CLASS_RT )
329 require the
330 .B CAP_SYS_ADMIN
331 capability.
332 Up to Linux 2.6.24 also required
333 .B CAP_SYS_ADMIN
334 to set a very low priority
335 .RB ( IOPRIO_CLASS_IDLE ),
336 but since Linux 2.6.25, this is no longer required.
337 .P
338 A call to
339 .BR ioprio_set ()
340 must follow both rules, or the call will fail with the error
341 .BR EPERM .
342 .SH BUGS
343 .\" 6 May 07: Bug report raised:
344 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=4464
345 .\" Ulrich Drepper replied that he wasn't going to add these
346 .\" to glibc.
347 glibc does not yet provide a suitable header file defining
348 the function prototypes and macros described on this page.
349 Suitable definitions can be found in
350 .IR linux/ioprio.h .
351 .SH SEE ALSO
352 .BR ionice (1),
353 .BR getpriority (2),
354 .BR open (2),
355 .BR capabilities (7),
356 .BR cgroups (7)
357 .P
358 .I Documentation/block/ioprio.rst
359 in the Linux kernel source tree