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@gmx.net>
  23 .\"
  24 .\"
  25 .TH IOPRIO_GET 2 2007-06-01 "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 .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
  67 .I which
  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
  86 has a higher priority level (a lower priority number means a
  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
 110 .IR mask
 111 (an
 112 .IR ioprio
 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
 122 .IR mask
 123 (an
 124 .IR ioprio
 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.
 131
 132 I/O priorities are supported for reads and for synchronous (O_DIRECT,
 133 O_SYNC) writes.
 134 I/O priorities are not supported for asynchronous
 135 writes because they are issued outside the context of the program
 136 dirtying the memory, and thus program-specific priorities do not apply.
 137 .SH "RETURN VALUE"
 138 On success,
 139 .BR ioprio_get ()
 140 returns the
 141 .I ioprio
 142 value of the process with highest I/O priority of any of the processes
 143 that match the criteria specified in
 144 .I which
 145 and
 146 .IR who .
 147 On error, \-1 is returned, and
 148 .I errno
 149 is set to indicate the error.
 150 .PP
 151 On success,
 152 .BR ioprio_set ()
 153 returns 0.
 154 On error, \-1 is returned, and
 155 .I errno
 156 is set to indicate the error.
 157 .SH ERRORS
 158 .TP
 159 .B EPERM
 160 The calling process does not have the privilege needed to assign this
 161 .I ioprio
 162 to the specified process(es).
 163 See the NOTES section for more information on required
 164 privileges for
 165 .BR ioprio_set ().
 166 .TP
 167 .B ESRCH
 168 No process(es) could be found that matched the specification in
 169 .I which
 170 and
 171 .IR who .
 172 .TP
 173 .B EINVAL
 174 Invalid value for
 175 .I which
 176 or
 177 .IR ioprio .
 178 Refer to the NOTES section for available scheduler
 179 classes and priority levels for
 180 .IR ioprio .
 181 .SH VERSIONS
 182 These system calls have been available on Linux since
 183 kernel 2.6.13.
 184 .SH "CONFORMING TO"
 185 These system calls are Linux specific.
 186 .SH NOTES
 187 Glibc does not provide wrapper for these system calls; call them using
 188 .BR syscall (2).
 189
 190 These system calls only have an effect when used
 191 in conjunction with an I/O scheduler that supports I/O priorities.
 192 As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
 193 (CFQ) I/O scheduler.
 194 .SS "Selecting an I/O Scheduler"
 195 I/O Schedulers are selected on a per-device basis via the special
 196 file
 197 .IR /sys/block/<device>/queue/scheduler .
 198
 199 One can view the current I/O scheduler via the
 200 .I /sys
 201 file system.
 202 For example, the following command
 203 displays a list of all schedulers currently loaded in the kernel:
 204 .sp
 205 .RS
 206 .nf
 207 $ cat /sys/block/hda/queue/scheduler
 208 noop anticipatory deadline [cfq]
 209 .fi
 210 .RE
 211 .sp
 212 The scheduler surrounded by brackets is the one actually
 213 in use for the device
 214 .RI ( hda
 215 in the example).
 216 Setting another scheduler is done by writing the name of the
 217 new scheduler to this file.
 218 For example, the following command will set the
 219 scheduler for the
 220 .I hda
 221 device to
 222 .IR cfq :
 223 .sp
 224 .RS
 225 .nf
 226 $ su
 227 Password:
 228 # echo cfq > /sys/block/hda/queue/scheduler
 229 .fi
 230 .RE
 231 .SS "The Completely Fair Queuing (CFQ) I/O Scheduler"
 232 Since v3 (aka CFQ Time Sliced) CFQ implements
 233 I/O nice levels similar to those
 234 of CPU scheduling.
 235 These nice levels are grouped in three scheduling classes
 236 each one containing one or more priority levels:
 237 .TP
 238 .BR IOPRIO_CLASS_RT " (1)"
 239 This is the real-time I/O class.
 240 This scheduling class is given
 241 higher priority than any other class:
 242 processes from this class are
 243 given first access to the disk every time.
 244 Thus this I/O class needs to be used with some
 245 care: one I/O real-time process can starve the entire system.
 246 Within the real-time class,
 247 there are 8 levels of class data (priority) that determine exactly
 248 how much time this process needs the disk for on each service.
 249 The highest real-time priority level is 0; the lowest is 7.
 250 In the future this might change to be more directly mappable to
 251 performance, by passing in a desired data rate instead.
 252 .TP
 253 .BR IOPRIO_CLASS_BE " (2)"
 254 This is the best-effort scheduling class,
 255 which is the default for any process
 256 that hasn't set a specific I/O priority.
 257 The class data (priority) determines how much
 258 I/O bandwidth the process will get.
 259 Best-effort priority levels are analogous to CPU nice values
 260 (see
 261 .BR getpriority (2)).
 262 The priority level determines a priority relative
 263 to other processes in the best-effort scheduling class.
 264 Priority levels range from 0 (highest) to 7 (lowest).
 265 .TP
 266 .BR IOPRIO_CLASS_IDLE " (3)"
 267 This is the idle scheduling class.
 268 Processes running at this level only get I/O
 269 time when no one else needs the disk.
 270 The idle class has no class
 271 data.
 272 Attention is required when assigning this priority class to a process,
 273 since it may become starved if higher priority processes are
 274 constantly accessing the disk.
 275 .PP
 276 Refer to
 277 .I Documentation/block/ioprio.txt
 278 for more information on the CFQ I/O Scheduler and an example program.
 279 .SS "Required permissions to set I/O priorities"
 280 Permission to change a process's priority is granted or denied based
 281 on two assertions:
 282 .TP
 283 .B "Process ownership"
 284 An unprivileged process may only set the I/O priority of a process
 285 whose real UID
 286 matches the real or effective UID of the calling process.
 287 A process which has the
 288 .B CAP_SYS_NICE
 289 capability can change the priority of any process.
 290 .TP
 291 .B "What is the desired priority"
 292 Attempts to set very high priorities
 293 .RB ( IOPRIO_CLASS_RT )
 294 or very low ones
 295 .RB ( IOPRIO_CLASS_IDLE )
 296 require the
 297 .B CAP_SYS_ADMIN
 298 capability.
 299 .PP
 300 A call to
 301 .BR ioprio_set ()
 302 must follow both rules, or the call will fail with the error
 303 .BR EPERM .
 304 .SH BUGS
 305 .\" 6 May 07: Bug report raised:
 306 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
 307 .\" Ulriich Drepper replied that he wasn't going to add these
 308 .\" to glibc.
 309 Glibc does not yet provide a suitable header file defining
 310 the function prototypes and macros described on this page.
 311 Suitable definitions can be found in
 312 .IR linux/ioprio.h .
 313 .SH "SEE ALSO"
 314 .BR getpriority "(2), " open "(2), " capabilities (7)
 315 .sp
 316 Documentation/block/ioprio.txt in the kernel source tree.