man2/ioprio_set.2

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