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