2006-05-24 20:47:23 +00:00
|
|
|
.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
|
|
|
|
.\"
|
2006-06-20 08:00:10 +00:00
|
|
|
.\" Copyright (c) International Business Machines orp., 2006
|
2006-05-24 20:47:23 +00:00
|
|
|
.\"
|
2006-06-20 08:00:10 +00:00
|
|
|
.\" This program is free software; you can redistribute it and/or
|
2006-05-24 20:47:23 +00:00
|
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
|
|
.\" the License, or (at your option) any later version.
|
|
|
|
.\"
|
|
|
|
.\" This program is distributed in the hope that it will be useful,
|
2006-06-20 08:00:10 +00:00
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
2006-05-24 20:47:23 +00:00
|
|
|
.\" the GNU General Public License for more details.
|
|
|
|
.\"
|
|
|
|
.\" You should have received a copy of the GNU General Public License
|
2006-06-20 08:00:10 +00:00
|
|
|
.\" along with this program; if not, write to the Free Software
|
2006-05-24 20:47:23 +00:00
|
|
|
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
|
|
|
.\" MA 02111-1307 USA
|
|
|
|
.\"
|
|
|
|
.\" HISTORY:
|
|
|
|
.\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com>
|
2006-05-24 20:47:23 +00:00
|
|
|
.\"
|
|
|
|
.\"
|
2007-11-16 06:23:33 +00:00
|
|
|
.TH IOPRIO_SET 2 2007-06-01 "Linux" "Linux Programmer's Manual"
|
2006-05-24 20:47:23 +00:00
|
|
|
.SH NAME
|
|
|
|
ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.BI "int ioprio_get(int " which ", int " who );
|
|
|
|
.BI "int ioprio_set(int " which ", int " who ", int " ioprio );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
|
|
|
.BR ioprio_get ()
|
|
|
|
and
|
|
|
|
.BR ioprio_set ()
|
|
|
|
system calls respectively get and set the I/O scheduling class and
|
|
|
|
priority of one or more processes.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I which
|
|
|
|
and
|
|
|
|
.I who
|
|
|
|
arguments identify the process(es) on which the system
|
|
|
|
calls operate.
|
|
|
|
The
|
|
|
|
.I which
|
|
|
|
argument determines how
|
|
|
|
.I who
|
|
|
|
is interpreted, and has one of the following values:
|
|
|
|
.TP
|
|
|
|
.B IOPRIO_WHO_PROCESS
|
|
|
|
.I who
|
|
|
|
is a process ID identifying a single process.
|
|
|
|
.TP
|
|
|
|
.B IOPRIO_WHO_PGRP
|
|
|
|
.I who
|
|
|
|
is a process group ID identifying all the members of a process group.
|
|
|
|
.TP
|
|
|
|
.B IOPRIO_WHO_USER
|
|
|
|
.I who
|
|
|
|
is a user ID identifying all of the processes that
|
|
|
|
have a matching real UID.
|
|
|
|
.PP
|
|
|
|
If
|
2006-12-27 02:39:51 +00:00
|
|
|
.I which
|
2006-05-24 20:47:23 +00:00
|
|
|
is specified as
|
|
|
|
.B IOPRIO_WHO_PGRP
|
|
|
|
or
|
|
|
|
.B IOPRIO_WHO_USER
|
|
|
|
when calling
|
|
|
|
.BR ioprio_get (),
|
|
|
|
and more than one process matches
|
|
|
|
.IR who ,
|
|
|
|
then the returned priority will be the highest one found among
|
|
|
|
all of the matching processes.
|
|
|
|
One priority is said to be
|
|
|
|
higher than another one if it belongs to a higher priority
|
|
|
|
class
|
|
|
|
.RB ( IOPRIO_CLASS_RT
|
|
|
|
is the highest priority class;
|
|
|
|
.B IOPRIO_CLASS_IDLE
|
|
|
|
is the lowest)
|
|
|
|
or if it belongs to the same priority class as the other process but
|
2006-06-20 08:00:10 +00:00
|
|
|
has a higher priority level (a lower priority number means a
|
2006-05-24 20:47:23 +00:00
|
|
|
higher priority level).
|
|
|
|
|
|
|
|
The
|
|
|
|
.I ioprio
|
|
|
|
argument given to
|
|
|
|
.BR ioprio_set ()
|
|
|
|
is a bit mask that specifies both the scheduling class and the
|
|
|
|
priority to be assigned to the target process(es).
|
|
|
|
The following macros are used for assembling and dissecting
|
|
|
|
.I ioprio
|
|
|
|
values:
|
|
|
|
.TP
|
|
|
|
.BI IOPRIO_PRIO_VALUE( class ", " data )
|
|
|
|
Given a scheduling
|
|
|
|
.I class
|
|
|
|
and priority
|
|
|
|
.RI ( data ),
|
|
|
|
this macro combines the two values to produce an
|
|
|
|
.I ioprio
|
|
|
|
value, which is returned as the result of the macro.
|
|
|
|
.TP
|
|
|
|
.BI IOPRIO_PRIO_CLASS( mask )
|
|
|
|
Given
|
2007-09-20 16:26:31 +00:00
|
|
|
.I mask
|
2006-05-24 20:47:23 +00:00
|
|
|
(an
|
2007-09-20 16:26:31 +00:00
|
|
|
.I ioprio
|
2006-05-24 20:47:23 +00:00
|
|
|
value), this macro returns its I/O class component, that is,
|
|
|
|
one of the values
|
|
|
|
.BR IOPRIO_CLASS_RT ,
|
|
|
|
.BR IOPRIO_CLASS_BE ,
|
|
|
|
or
|
|
|
|
.BR IOPRIO_CLASS_IDLE .
|
|
|
|
.TP
|
|
|
|
.BI IOPRIO_PRIO_DATA( mask )
|
|
|
|
Given
|
2007-09-20 16:26:31 +00:00
|
|
|
.I mask
|
2006-05-24 20:47:23 +00:00
|
|
|
(an
|
2007-09-20 16:26:31 +00:00
|
|
|
.I ioprio
|
2006-05-24 20:47:23 +00:00
|
|
|
value), this macro returns its priority
|
|
|
|
.RI ( data )
|
|
|
|
component.
|
|
|
|
.PP
|
|
|
|
See the NOTES section for more
|
|
|
|
information on scheduling classes and priorities.
|
2006-06-20 08:00:10 +00:00
|
|
|
|
2007-06-22 17:16:20 +00:00
|
|
|
I/O priorities are supported for reads and for synchronous
|
|
|
|
.RB ( O_DIRECT ,
|
|
|
|
.BR O_SYNC )
|
|
|
|
writes.
|
2007-04-12 22:42:49 +00:00
|
|
|
I/O priorities are not supported for asynchronous
|
2006-06-20 08:00:10 +00:00
|
|
|
writes because they are issued outside the context of the program
|
|
|
|
dirtying the memory, and thus program-specific priorities do not apply.
|
2006-05-24 20:47:23 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success,
|
|
|
|
.BR ioprio_get ()
|
|
|
|
returns the
|
|
|
|
.I ioprio
|
|
|
|
value of the process with highest I/O priority of any of the processes
|
|
|
|
that match the criteria specified in
|
|
|
|
.I which
|
|
|
|
and
|
|
|
|
.IR who .
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the error.
|
|
|
|
.PP
|
|
|
|
On success,
|
|
|
|
.BR ioprio_set ()
|
|
|
|
returns 0.
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set to indicate the error.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
2007-08-27 07:56:52 +00:00
|
|
|
.B EINVAL
|
|
|
|
Invalid value for
|
|
|
|
.I which
|
|
|
|
or
|
|
|
|
.IR ioprio .
|
|
|
|
Refer to the NOTES section for available scheduler
|
|
|
|
classes and priority levels for
|
|
|
|
.IR ioprio .
|
|
|
|
.TP
|
2006-05-24 20:47:23 +00:00
|
|
|
.B EPERM
|
|
|
|
The calling process does not have the privilege needed to assign this
|
|
|
|
.I ioprio
|
|
|
|
to the specified process(es).
|
|
|
|
See the NOTES section for more information on required
|
|
|
|
privileges for
|
|
|
|
.BR ioprio_set ().
|
|
|
|
.TP
|
|
|
|
.B ESRCH
|
|
|
|
No process(es) could be found that matched the specification in
|
|
|
|
.I which
|
|
|
|
and
|
|
|
|
.IR who .
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
These system calls have been available on Linux since
|
|
|
|
kernel 2.6.13.
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
These system calls are Linux specific.
|
2006-05-24 20:47:23 +00:00
|
|
|
.SH NOTES
|
2007-05-26 15:22:28 +00:00
|
|
|
Glibc does not provide wrapper for these system calls; call them using
|
|
|
|
.BR syscall (2).
|
|
|
|
|
2006-05-24 20:47:23 +00:00
|
|
|
These system calls only have an effect when used
|
|
|
|
in conjunction with an I/O scheduler that supports I/O priorities.
|
2006-06-20 08:00:10 +00:00
|
|
|
As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing
|
2006-05-24 20:47:23 +00:00
|
|
|
(CFQ) I/O scheduler.
|
|
|
|
.SS "Selecting an I/O Scheduler"
|
|
|
|
I/O Schedulers are selected on a per-device basis via the special
|
|
|
|
file
|
|
|
|
.IR /sys/block/<device>/queue/scheduler .
|
|
|
|
|
|
|
|
One can view the current I/O scheduler via the
|
|
|
|
.I /sys
|
|
|
|
file system.
|
|
|
|
For example, the following command
|
|
|
|
displays a list of all schedulers currently loaded in the kernel:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
$ cat /sys/block/hda/queue/scheduler
|
|
|
|
noop anticipatory deadline [cfq]
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
The scheduler surrounded by brackets is the one actually
|
|
|
|
in use for the device
|
|
|
|
.RI ( hda
|
|
|
|
in the example).
|
|
|
|
Setting another scheduler is done by writing the name of the
|
|
|
|
new scheduler to this file.
|
2006-08-09 15:08:53 +00:00
|
|
|
For example, the following command will set the
|
2006-05-24 20:47:23 +00:00
|
|
|
scheduler for the
|
|
|
|
.I hda
|
|
|
|
device to
|
|
|
|
.IR cfq :
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
$ su
|
|
|
|
Password:
|
|
|
|
# echo cfq > /sys/block/hda/queue/scheduler
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.SS "The Completely Fair Queuing (CFQ) I/O Scheduler"
|
|
|
|
Since v3 (aka CFQ Time Sliced) CFQ implements
|
|
|
|
I/O nice levels similar to those
|
|
|
|
of CPU scheduling.
|
|
|
|
These nice levels are grouped in three scheduling classes
|
|
|
|
each one containing one or more priority levels:
|
|
|
|
.TP
|
|
|
|
.BR IOPRIO_CLASS_RT " (1)"
|
2007-04-12 22:42:49 +00:00
|
|
|
This is the real-time I/O class.
|
|
|
|
This scheduling class is given
|
2006-05-24 20:47:23 +00:00
|
|
|
higher priority than any other class:
|
|
|
|
processes from this class are
|
|
|
|
given first access to the disk every time.
|
|
|
|
Thus this I/O class needs to be used with some
|
|
|
|
care: one I/O real-time process can starve the entire system.
|
|
|
|
Within the real-time class,
|
|
|
|
there are 8 levels of class data (priority) that determine exactly
|
|
|
|
how much time this process needs the disk for on each service.
|
|
|
|
The highest real-time priority level is 0; the lowest is 7.
|
|
|
|
In the future this might change to be more directly mappable to
|
|
|
|
performance, by passing in a desired data rate instead.
|
|
|
|
.TP
|
|
|
|
.BR IOPRIO_CLASS_BE " (2)"
|
|
|
|
This is the best-effort scheduling class,
|
|
|
|
which is the default for any process
|
|
|
|
that hasn't set a specific I/O priority.
|
|
|
|
The class data (priority) determines how much
|
|
|
|
I/O bandwidth the process will get.
|
|
|
|
Best-effort priority levels are analogous to CPU nice values
|
|
|
|
(see
|
|
|
|
.BR getpriority (2)).
|
|
|
|
The priority level determines a priority relative
|
|
|
|
to other processes in the best-effort scheduling class.
|
|
|
|
Priority levels range from 0 (highest) to 7 (lowest).
|
|
|
|
.TP
|
|
|
|
.BR IOPRIO_CLASS_IDLE " (3)"
|
|
|
|
This is the idle scheduling class.
|
|
|
|
Processes running at this level only get I/O
|
2007-04-12 22:42:49 +00:00
|
|
|
time when no one else needs the disk.
|
|
|
|
The idle class has no class
|
|
|
|
data.
|
2006-08-09 15:08:53 +00:00
|
|
|
Attention is required when assigning this priority class to a process,
|
2006-05-24 20:47:23 +00:00
|
|
|
since it may become starved if higher priority processes are
|
|
|
|
constantly accessing the disk.
|
|
|
|
.PP
|
|
|
|
Refer to
|
|
|
|
.I Documentation/block/ioprio.txt
|
|
|
|
for more information on the CFQ I/O Scheduler and an example program.
|
|
|
|
.SS "Required permissions to set I/O priorities"
|
|
|
|
Permission to change a process's priority is granted or denied based
|
|
|
|
on two assertions:
|
|
|
|
.TP
|
|
|
|
.B "Process ownership"
|
|
|
|
An unprivileged process may only set the I/O priority of a process
|
|
|
|
whose real UID
|
|
|
|
matches the real or effective UID of the calling process.
|
|
|
|
A process which has the
|
|
|
|
.B CAP_SYS_NICE
|
|
|
|
capability can change the priority of any process.
|
|
|
|
.TP
|
|
|
|
.B "What is the desired priority"
|
|
|
|
Attempts to set very high priorities
|
|
|
|
.RB ( IOPRIO_CLASS_RT )
|
|
|
|
or very low ones
|
|
|
|
.RB ( IOPRIO_CLASS_IDLE )
|
|
|
|
require the
|
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability.
|
|
|
|
.PP
|
|
|
|
A call to
|
|
|
|
.BR ioprio_set ()
|
|
|
|
must follow both rules, or the call will fail with the error
|
|
|
|
.BR EPERM .
|
|
|
|
.SH BUGS
|
2007-05-06 07:01:35 +00:00
|
|
|
.\" 6 May 07: Bug report raised:
|
|
|
|
.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=4464
|
2007-05-27 15:23:47 +00:00
|
|
|
.\" Ulriich Drepper replied that he wasn't going to add these
|
|
|
|
.\" to glibc.
|
2006-05-24 20:47:23 +00:00
|
|
|
Glibc does not yet provide a suitable header file defining
|
|
|
|
the function prototypes and macros described on this page.
|
|
|
|
Suitable definitions can be found in
|
|
|
|
.IR linux/ioprio.h .
|
|
|
|
.SH "SEE ALSO"
|
2006-06-20 08:00:10 +00:00
|
|
|
.BR getpriority "(2), " open "(2), " capabilities (7)
|
2006-05-24 20:47:23 +00:00
|
|
|
.sp
|
|
|
|
Documentation/block/ioprio.txt in the kernel source tree.
|