diff options
Diffstat (limited to 'man2/ioprio_set.2')
| -rw-r--r-- | man2/ioprio_set.2 | 362 |
1 files changed, 362 insertions, 0 deletions
diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 new file mode 100644 index 0000000..7770cbc --- /dev/null +++ b/man2/ioprio_set.2 @@ -0,0 +1,362 @@ +.\" Copyright (c) International Business Machines orp., 2006 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" HISTORY: +.\" 2006-04-27, created by Eduardo M. Fleury <efleury@br.ibm.com> +.\" with various additions by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" +.TH ioprio_set 2 2023-04-03 "Linux man-pages 6.05.01" +.SH NAME +ioprio_get, ioprio_set \- get/set I/O scheduling class and priority +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/ioprio.h> " "/* Definition of " IOPRIO_* " constants */" +.BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.PP +.BI "int syscall(SYS_ioprio_get, int " which ", int " who ); +.BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio ); +.fi +.PP +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR ioprio_get () +and +.BR ioprio_set () +system calls get and set the I/O scheduling class and +priority of one or more threads. +.PP +The +.I which +and +.I who +arguments identify the thread(s) 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 or thread ID identifying a single process or thread. +If +.I who +is 0, then operate on the calling thread. +.TP +.B IOPRIO_WHO_PGRP +.I who +is a process group ID identifying all the members of a process group. +If +.I who +is 0, then operate on the process group of which the caller is a member. +.TP +.B IOPRIO_WHO_USER +.I who +is a user ID identifying all of the processes that +have a matching real UID. +.\" FIXME . Need to document the behavior when 'who" is specified as 0 +.\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 +.PP +If +.I which +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). +.PP +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 +.I mask +(an +.I 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 +.I mask +(an +.I ioprio +value), this macro returns its priority +.RI ( data ) +component. +.PP +See the NOTES section for more +information on scheduling classes and priorities, +as well as the meaning of specifying +.I ioprio +as 0. +.PP +I/O priorities are supported for reads and for synchronous +.RB ( O_DIRECT , +.BR 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 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 +.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 . +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.13. +.SH NOTES +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). +.PP +These system calls have an effect only 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. +.PP +If no I/O scheduler has been set for a thread, +then by default the I/O priority will follow the CPU nice value +.RB ( setpriority (2)). +Before Linux 2.6.24, +once an I/O priority had been set using +.BR ioprio_set (), +there was no way to reset the I/O scheduling behavior to the default. +Since Linux 2.6.24, +.\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550 +specifying +.I ioprio +as 0 can be used to reset to the default I/O scheduling behavior. +.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 . +.PP +One can view the current I/O scheduler via the +.I /sys +filesystem. +For example, the following command +displays a list of all schedulers currently loaded in the kernel: +.PP +.in +4n +.EX +.RB "$" " cat /sys/block/sda/queue/scheduler" +noop anticipatory deadline [cfq] +.EE +.in +.PP +The scheduler surrounded by brackets is the one actually +in use for the device +.RI ( sda +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 sda +device to +.IR cfq : +.PP +.in +4n +.EX +.RB "$" " su" +Password: +.RB "#" " echo cfq > /sys/block/sda/queue/scheduler" +.EE +.in +.\" +.SS The Completely Fair Queuing (CFQ) I/O scheduler +Since version 3 (also known as CFQ Time Sliced), CFQ implements +I/O nice levels similar to those +of CPU scheduling. +These nice levels are grouped into 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 get I/O +time only 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 the kernel source file +.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 criteria: +.TP +.B "Process ownership" +An unprivileged process may set the I/O priority only for 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. +Up to Linux 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. +.PP +A call to +.BR ioprio_set () +must follow both rules, or the call will fail with the error +.BR EPERM . +.SH BUGS +.\" 6 May 07: Bug report raised: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=4464 +.\" Ulrich Drepper replied that he wasn't going to add these +.\" to glibc. +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 +.BR ionice (1), +.BR getpriority (2), +.BR open (2), +.BR capabilities (7), +.BR cgroups (7) +.PP +.I Documentation/block/ioprio.txt +in the Linux kernel source tree |