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
|
|
|
.\"
|
|
|
|
.\"
|
2012-07-29 05:08:23 +00:00
|
|
|
.TH IOPRIO_SET 2 2012-07-29 "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
|
get_robust_list.2, get_thread_area.2, getcpu.2, getdents.2, gettid.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, ioprio_set.2, kexec_load.2, llseek.2, modify_ldt.2, mq_getsetattr.2, pivot_root.2, readdir.2, rt_sigqueueinfo.2, set_thread_area.2, sgetmask.2, spu_create.2, spu_run.2, subpage_prot.2, sysctl.2, tkill.2: Add note to SYNOPSIS that there is no glibc wrapper for system call
Reduce the chance that the reader may be misled into thinking
that there is a wrapper function for this system call by noting
explicitly in the SYNOPSIS that there is no glibc wrapper and
pointing the reader to NOTES for further details.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-07-13 06:48:20 +00:00
|
|
|
|
|
|
|
.IR Note :
|
|
|
|
There are no glibc wrappers for these system calls; see NOTES.
|
2006-05-24 20:47:23 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
|
|
|
.BR ioprio_get ()
|
|
|
|
and
|
|
|
|
.BR ioprio_set ()
|
|
|
|
system calls respectively get and set the I/O scheduling class and
|
2012-07-29 05:08:23 +00:00
|
|
|
priority of one or more threads.
|
2006-05-24 20:47:23 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.I which
|
|
|
|
and
|
|
|
|
.I who
|
2012-07-29 05:08:23 +00:00
|
|
|
arguments identify the thread(s) on which the system
|
2006-05-24 20:47:23 +00:00
|
|
|
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
|
2012-07-29 05:08:23 +00:00
|
|
|
is a process ID or thread ID identifying a single process or thread.
|
2012-07-29 06:07:43 +00:00
|
|
|
If
|
|
|
|
.I who
|
|
|
|
is 0, then operate on the calling thread.
|
2006-05-24 20:47:23 +00:00
|
|
|
.TP
|
|
|
|
.B IOPRIO_WHO_PGRP
|
|
|
|
.I who
|
|
|
|
is a process group ID identifying all the members of a process group.
|
2012-07-29 06:07:43 +00:00
|
|
|
If
|
|
|
|
.I who
|
|
|
|
is 0, then operate on the process group of which the caller is a member.
|
2006-05-24 20:47:23 +00:00
|
|
|
.TP
|
|
|
|
.B IOPRIO_WHO_USER
|
|
|
|
.I who
|
|
|
|
is a user ID identifying all of the processes that
|
|
|
|
have a matching real UID.
|
2012-08-13 22:39:21 +00:00
|
|
|
.\" FIXME who==0 needs to be documented,
|
2012-07-29 06:07:43 +00:00
|
|
|
.\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
|
2006-05-24 20:47:23 +00:00
|
|
|
.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"
|
2007-12-25 21:28:09 +00:00
|
|
|
These system calls are Linux-specific.
|
2006-05-24 20:47:23 +00:00
|
|
|
.SH NOTES
|
2012-07-29 05:13:48 +00:00
|
|
|
Glibc does not provide a wrapper for these system calls; call them using
|
2007-05-26 15:22:28 +00:00
|
|
|
.BR syscall (2).
|
|
|
|
|
2012-07-29 05:08:23 +00:00
|
|
|
Two or more processes or threads can share an I/O context.
|
|
|
|
This will be the case when
|
|
|
|
.BR clone (2)
|
|
|
|
was called with the
|
|
|
|
.B CLONE_IO
|
|
|
|
flag.
|
|
|
|
However, by default, the distinct threads of a process will
|
|
|
|
.B not
|
|
|
|
share the same I/O context.
|
|
|
|
This means that if you want to change the I/O
|
|
|
|
priority of all threads in a process, you may need to call
|
|
|
|
.BR ioprio_set ()
|
|
|
|
on each of the threads.
|
|
|
|
The thread ID that you would need for this operation
|
|
|
|
is the one that is returned by
|
|
|
|
.BR gettid (2)
|
|
|
|
or
|
|
|
|
.BR clone (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
|
eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, malloc.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7: Global fix: Format user input in shell sessions in boldface
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:37:22 +00:00
|
|
|
.RB "$" " cat /sys/block/hda/queue/scheduler"
|
2006-05-24 20:47:23 +00:00
|
|
|
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
|
eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, malloc.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7: Global fix: Format user input in shell sessions in boldface
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:37:22 +00:00
|
|
|
.RB "$" " su"
|
2006-05-24 20:47:23 +00:00
|
|
|
Password:
|
eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, malloc.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7: Global fix: Format user input in shell sessions in boldface
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:37:22 +00:00
|
|
|
.RB "#" " echo cfq > /sys/block/hda/queue/scheduler"
|
2006-05-24 20:47:23 +00:00
|
|
|
.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-12-26 11:46:23 +00:00
|
|
|
time when no-one else needs the disk.
|
2008-07-08 10:12:21 +00:00
|
|
|
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 )
|
|
|
|
require the
|
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability.
|
2008-07-08 10:12:21 +00:00
|
|
|
Kernel versions up to 2.6.24 also required
|
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
to set a very low priority
|
|
|
|
.RB ( IOPRIO_CLASS_IDLE ),
|
|
|
|
but since Linux 2.6.25, this is no longer required.
|
2006-05-24 20:47:23 +00:00
|
|
|
.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
|
2010-06-20 01:46:36 +00:00
|
|
|
.\" Ulrich Drepper replied that he wasn't going to add these
|
2007-05-27 15:23:47 +00:00
|
|
|
.\" 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"
|
2013-02-11 22:54:51 +00:00
|
|
|
.BR ionice (1),
|
2009-01-20 02:14:57 +00:00
|
|
|
.BR getpriority (2),
|
2009-02-09 02:12:23 +00:00
|
|
|
.BR open (2),
|
2009-01-20 02:14:57 +00:00
|
|
|
.BR capabilities (7)
|
arch_prctl.2, fcntl.2, flock.2, get_robust_list.2, getpriority.2, ioprio_set.2, migrate_pages.2, mmap.2, mremap.2, msync.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, select.2, socket.2, subpage_prot.2, unshare.2, btree.3, dbopen.3, dl_iterate_phdr.3, dlopen.3, getnameinfo.3, hash.3, lockf.3, netlink.3, recno.3, rpc.3, xdr.3, cciss.4, console_ioctl.4, hpsa.4, initrd.4, msr.4, rtc.4, st.4, hosts.5, services.5, tzfile.5, aio.7, arp.7, capabilities.7, cpuset.7, feature_test_macros.7, futex.7, inotify.7, ip.7, ipv6.7, iso_8859-16.7, iso_8859-2.7, koi8-r.7, math_error.7, netlink.7, packet.7, pthreads.7, raw.7, spufs.7, udplite.7, uri.7, x25.7: Global fix: Various consistency fixes for SEE ALSO
Coauthored-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-09-24 07:53:22 +00:00
|
|
|
|
|
|
|
.I Documentation/block/ioprio.txt
|
|
|
|
in the Linux kernel source tree
|