mirror of https://github.com/mkerrisk/man-pages
318 lines
8.7 KiB
Groff
318 lines
8.7 KiB
Groff
.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
|
|
.\"
|
|
.\" Copyright (c) International Business Machines orp., 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>
|
|
.\"
|
|
.\"
|
|
.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 higher priority level (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.
|
|
|
|
I/O priorities are supported for reads and for synchronous (O_DIRECT,
|
|
O_SYNC) writes. I/O priorities are not supported for asynchronous
|
|
writes because they are issued outside the context of the program
|
|
dirtying the memory, and thus program-specific priorities do not apply.
|
|
|
|
.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.17 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
|
|
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 to a 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 "CONFORMING TO"
|
|
These system calls are Linux specific.
|
|
.SH "SEE ALSO"
|
|
.BR getpriority "(2), " open "(2), " capabilities (7)
|
|
.sp
|
|
Documentation/block/ioprio.txt in the kernel source tree.
|