summaryrefslogtreecommitdiffstats
path: root/man2/ioprio_set.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/ioprio_set.2')
-rw-r--r--man2/ioprio_set.2362
1 files changed, 0 insertions, 362 deletions
diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2
deleted file mode 100644
index 629d2df..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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>
-.P
-.BI "int syscall(SYS_ioprio_get, int " which ", int " who );
-.BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio );
-.fi
-.P
-.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.
-.P
-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
-.P
-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).
-.P
-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.
-.P
-See the NOTES section for more
-information on scheduling classes and priorities,
-as well as the meaning of specifying
-.I ioprio
-as 0.
-.P
-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.
-.P
-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).
-.P
-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.
-.P
-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 .
-.P
-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:
-.P
-.in +4n
-.EX
-.RB "$" " cat /sys/block/sda/queue/scheduler"
-noop anticipatory deadline [cfq]
-.EE
-.in
-.P
-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 :
-.P
-.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.
-.P
-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.
-.P
-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)
-.P
-.I Documentation/block/ioprio.txt
-in the Linux kernel source tree