diff options
Diffstat (limited to 'man2/ioprio_set.2')
| -rw-r--r-- | man2/ioprio_set.2 | 362 |
1 files changed, 0 insertions, 362 deletions
diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 deleted file mode 100644 index a232686c8..000000000 --- a/man2/ioprio_set.2 +++ /dev/null @@ -1,362 +0,0 @@ -.\" 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 (date) "Linux man-pages (unreleased)" -.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 |