mirror of https://github.com/mkerrisk/man-pages
New page for ioprio_set(2)
This commit is contained in:
Michael Kerrisk
parent
7b2d525933
commit
5b3b2ce10b
|
|
@ -0,0 +1,320 @@
|
|||
.\" 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.
|
||||
Loading…
Reference in New Issue