man2/ioprio_set.2

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