Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 362 insertions, 0 deletions

diff --git a/man/man2/ioprio_set.2 b/man/man2/ioprio_set.2
new file mode 100644
index 0000000..ae744ba
--- /dev/null
+++ b/man/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 2024-05-02 "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>
+.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