Merging upstream version 6.8.

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

1 files changed, 250 insertions, 0 deletions

diff --git a/man/man2/getrusage.2 b/man/man2/getrusage.2
new file mode 100644
index 0000000..ff640e2
--- /dev/null
+++ b/man/man2/getrusage.2
@@ -0,0 +1,250 @@
+'\" t
+.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992
+.\" and Copyright (c) 2002 Michael Kerrisk
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formerly included
+.\" coverage of getrusage(2), has been split, so that the latter is
+.\" now covered in its own getrusage.2.  For older details of change
+.\" history, etc., see getrlimit.2
+.\"
+.\" Modified 2004-11-16, mtk, Noted that the nonconformance
+.\"	when SIGCHLD is being ignored is fixed in Linux 2.6.9.
+.\" 2008-02-22, Sripathi Kodi <sripathik@in.ibm.com>: Document RUSAGE_THREAD
+.\" 2008-05-25, mtk, clarify RUSAGE_CHILDREN + other clean-ups.
+.\" 2010-05-24, Mark Hills <mark@pogo.org.uk>: Description of fields,
+.\"     document ru_maxrss
+.\" 2010-05-24, mtk, enhanced description of various fields
+.\"
+.TH getrusage 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getrusage \- get resource usage
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/resource.h>
+.P
+.BI "int getrusage(int " who ", struct rusage *" usage );
+.fi
+.SH DESCRIPTION
+.BR getrusage ()
+returns resource usage measures for
+.IR who ,
+which can be one of the following:
+.TP
+.B RUSAGE_SELF
+Return resource usage statistics for the calling process,
+which is the sum of resources used by all threads in the process.
+.TP
+.B RUSAGE_CHILDREN
+Return resource usage statistics for all children of the
+calling process that have terminated and been waited for.
+These statistics will include the resources used by grandchildren,
+and further removed descendants,
+if all of the intervening descendants waited on their terminated children.
+.TP
+.BR RUSAGE_THREAD " (since Linux 2.6.26)"
+Return resource usage statistics for the calling thread.
+The
+.B _GNU_SOURCE
+feature test macro must be defined (before including
+.I any
+header file)
+in order to obtain the definition of this constant from
+.IR <sys/resource.h> .
+.P
+The resource usages are returned in the structure pointed to by
+.IR usage ,
+which has the following form:
+.P
+.in +4n
+.EX
+struct rusage {
+    struct timeval ru_utime; /* user CPU time used */
+    struct timeval ru_stime; /* system CPU time used */
+    long   ru_maxrss;        /* maximum resident set size */
+    long   ru_ixrss;         /* integral shared memory size */
+    long   ru_idrss;         /* integral unshared data size */
+    long   ru_isrss;         /* integral unshared stack size */
+    long   ru_minflt;        /* page reclaims (soft page faults) */
+    long   ru_majflt;        /* page faults (hard page faults) */
+    long   ru_nswap;         /* swaps */
+    long   ru_inblock;       /* block input operations */
+    long   ru_oublock;       /* block output operations */
+    long   ru_msgsnd;        /* IPC messages sent */
+    long   ru_msgrcv;        /* IPC messages received */
+    long   ru_nsignals;      /* signals received */
+    long   ru_nvcsw;         /* voluntary context switches */
+    long   ru_nivcsw;        /* involuntary context switches */
+};
+.EE
+.in
+.P
+Not all fields are completed;
+unmaintained fields are set to zero by the kernel.
+(The unmaintained fields are provided for compatibility with other systems,
+and because they may one day be supported on Linux.)
+The fields are interpreted as follows:
+.TP
+.I ru_utime
+This is the total amount of time spent executing in user mode,
+expressed in a
+.I timeval
+structure (seconds plus microseconds).
+.TP
+.I ru_stime
+This is the total amount of time spent executing in kernel mode,
+expressed in a
+.I timeval
+structure (seconds plus microseconds).
+.TP
+.IR ru_maxrss " (since Linux 2.6.32)"
+This is the maximum resident set size used (in kilobytes).
+For
+.BR RUSAGE_CHILDREN ,
+this is the resident set size of the largest child, not the maximum
+resident set size of the process tree.
+.TP
+.IR ru_ixrss " (unmaintained)"
+This field is currently unused on Linux.
+.\" On some systems,
+.\" this is the integral of the text segment memory consumption,
+.\" expressed in kilobyte-seconds.
+.TP
+.IR ru_idrss " (unmaintained)"
+This field is currently unused on Linux.
+.\" On some systems, this is the integral of the data segment memory consumption,
+.\" expressed in kilobyte-seconds.
+.TP
+.IR ru_isrss " (unmaintained)"
+This field is currently unused on Linux.
+.\" On some systems, this is the integral of the stack memory consumption,
+.\" expressed in kilobyte-seconds.
+.TP
+.I ru_minflt
+The number of page faults serviced without any I/O activity; here
+I/O activity is avoided by \*(lqreclaiming\*(rq a page frame from
+the list of pages awaiting reallocation.
+.TP
+.I ru_majflt
+The number of page faults serviced that required I/O activity.
+.TP
+.IR ru_nswap  " (unmaintained)"
+This field is currently unused on Linux.
+.\" On some systems, this is the number of swaps out of physical memory.
+.TP
+.IR ru_inblock " (since Linux 2.6.22)"
+The number of times the filesystem had to perform input.
+.TP
+.IR ru_oublock " (since Linux 2.6.22)"
+The number of times the filesystem had to perform output.
+.TP
+.IR ru_msgsnd " (unmaintained)"
+This field is currently unused on Linux.
+.\" On FreeBSD 6.2, this appears to measure messages sent over sockets
+.\" On some systems,
+.\" this field records the number of messages sent over sockets.
+.TP
+.IR ru_msgrcv " (unmaintained)"
+This field is currently unused on Linux.
+.\" On FreeBSD 6.2, this appears to measure messages received over sockets
+.\" On some systems,
+.\" this field records the number of messages received over sockets.
+.TP
+.IR ru_nsignals " (unmaintained)"
+This field is currently unused on Linux.
+.\" On some systems, this field records the number of signals received.
+.TP
+.IR ru_nvcsw " (since Linux 2.6)"
+The number of times a context switch resulted due to a process
+voluntarily giving up the processor before its time slice was
+completed (usually to await availability of a resource).
+.TP
+.IR ru_nivcsw " (since Linux 2.6)"
+The number of times a context switch resulted due to a higher
+priority process becoming runnable or because the current process
+exceeded its time slice.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+.I usage
+points outside the accessible address space.
+.TP
+.B EINVAL
+.I who
+is invalid.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getrusage ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.P
+POSIX.1 specifies
+.BR getrusage (),
+but specifies only the fields
+.I ru_utime
+and
+.IR ru_stime .
+.P
+.B RUSAGE_THREAD
+is Linux-specific.
+.SH HISTORY
+POSIX.1-2001, SVr4, 4.3BSD.
+.P
+Before Linux 2.6.9, if the disposition of
+.B SIGCHLD
+is set to
+.B SIG_IGN
+then the resource usages of child processes
+are automatically included in the value returned by
+.BR RUSAGE_CHILDREN ,
+although POSIX.1-2001 explicitly prohibits this.
+This nonconformance is rectified in Linux 2.6.9 and later.
+.\" See the description of getrusage() in XSH.
+.\" A similar statement was also in SUSv2.
+.P
+The structure definition shown at the start of this page
+was taken from 4.3BSD Reno.
+.P
+Ancient systems provided a
+.BR vtimes ()
+function with a similar purpose to
+.BR getrusage ().
+For backward compatibility, glibc (up until Linux 2.32) also provides
+.BR vtimes ().
+All new applications should be written using
+.BR getrusage ().
+(Since Linux 2.33, glibc no longer provides an
+.BR vtimes ()
+implementation.)
+.SH NOTES
+Resource usage metrics are preserved across an
+.BR execve (2).
+.SH SEE ALSO
+.BR clock_gettime (2),
+.BR getrlimit (2),
+.BR times (2),
+.BR wait (2),
+.BR wait4 (2),
+.BR clock (3),
+.BR proc_pid_stat (5),
+.BR proc_pid_io (5)