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