man2/ioprio_set.2

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