mirror of https://github.com/mkerrisk/man-pages
321 lines
8.9 KiB
Groff
321 lines
8.9 KiB
Groff
|
.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
|
||
|
.\"
|
||
|
.\" Copyright (c) International Business Machines Corp., 2006
|
||
|
.\"
|
||
|
.\" This program is free software; you can redistribute it and/or
|
||
|
.\" 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,
|
||
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
||
|
.\" the GNU General Public License for more details.
|
||
|
.\"
|
||
|
.\" You should have received a copy of the GNU General Public License
|
||
|
.\" along with this program; if not, write to the Free Software
|
||
|
.\" 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>
|
||
|
.\" with various additions by Michael Kerrisk <mtk-manpages@gmx.net>
|
||
|
.\"
|
||
|
.\" FIXME Documentation/block/ioprio.txt says:
|
||
|
.\" With the introduction of cfq v3 (aka cfq-ts or time sliced
|
||
|
.\" cfq), basic io priorities is supported for reads on files.
|
||
|
.\" Does some of this text need to be worked into the man page?
|
||
|
.\" Especially "supported for reads on files".
|
||
|
.\"
|
||
|
.\" FIXME
|
||
|
.\" We have some general problems:
|
||
|
.\" These calls aren't in glibc yet. Why aren't they there yet?
|
||
|
.\" Ask Jens Axboe about this. Perhaps something needs to be pushed
|
||
|
.\" to Ulrich Drepper so that suitable stuff ends up in the glibc
|
||
|
.\" tree.
|
||
|
.\"
|
||
|
.TH IOPRIO_GET 2 2006-04-27 "2.6.13" "Linux Programmer's Manual"
|
||
|
.SH NAME
|
||
|
ioprio_get, ioprio_set \- get/set I/O scheduling class and priority
|
||
|
.SH SYNOPSIS
|
||
|
.nf
|
||
|
.B #include <errno.h>
|
||
|
.B #include <linux/unistd.h>
|
||
|
.sp
|
||
|
.B _syscall2(int, ioprio_get, int, which, int, who);
|
||
|
.B _syscall3(int, ioprio_set, int, which, int, who, int, ioprio);
|
||
|
.RB " /* Using " syscall "(2) might be preferable; see " intro \
|
||
|
"(2) */"
|
||
|
.sp
|
||
|
.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
|
||
|
.I who
|
||
|
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
|
||
|
has a lower priority number (a lower priority number means a
|
||
|
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
|
||
|
.IR mask
|
||
|
(an
|
||
|
.IR ioprio
|
||
|
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
|
||
|
.IR mask
|
||
|
(an
|
||
|
.IR ioprio
|
||
|
value), this macro returns its priority
|
||
|
.RI ( data )
|
||
|
component.
|
||
|
.PP
|
||
|
See the NOTES section for more
|
||
|
information on scheduling classes and priorities.
|
||
|
.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
|
||
|
.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 .
|
||
|
.TP
|
||
|
.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 .
|
||
|
.SH NOTES
|
||
|
These system calls only have an effect when used
|
||
|
in conjunction with an I/O scheduler that supports I/O priorities.
|
||
|
As at kernel 2.6.16 the only such scheduler is the Completely Fair Queuing
|
||
|
(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.
|
||
|
For example, the following command will set the set the
|
||
|
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)"
|
||
|
This is the real-time I/O class. This scheduling class is given
|
||
|
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
|
||
|
time when no one else needs the disk. The idle class has no class
|
||
|
data. Attention is required when assigning this priority class process,
|
||
|
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
|
||
|
.\" FIXME . One day we must revisit this to see if glibc has
|
||
|
.\" the right stuff.
|
||
|
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 VERSIONS
|
||
|
These system calls have been available on Linux since
|
||
|
kernel 2.6.13.
|
||
|
.SH "SEE ALSO"
|
||
|
.BR getpriority "(2), " capabilities (7)
|
||
|
.sp
|
||
|
Documentation/block/ioprio.txt in the kernel source tree.
|