From 5b3b2ce10b05397a2dfa4ef8a6a077c3bedb4849 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 24 May 2006 20:47:23 +0000 Subject: [PATCH] New page for ioprio_set(2) --- man2/ioprio_set.2 | 320 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 man2/ioprio_set.2 diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 new file mode 100644 index 000000000..581c793a4 --- /dev/null +++ b/man2/ioprio_set.2 @@ -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 +.\" with various additions by Michael Kerrisk +.\" +.\" 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 +.B #include +.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//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.