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