summaryrefslogtreecommitdiffstats
path: root/man2/getrusage.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/getrusage.2')
-rw-r--r--man2/getrusage.2254
1 files changed, 254 insertions, 0 deletions
diff --git a/man2/getrusage.2 b/man2/getrusage.2
new file mode 100644
index 0000000..8966295
--- /dev/null
+++ b/man2/getrusage.2
@@ -0,0 +1,254 @@
+'\" 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 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+getrusage \- get resource usage
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/resource.h>
+.PP
+.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> .
+.PP
+The resource usages are returned in the structure pointed to by
+.IR usage ,
+which has the following form:
+.PP
+.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
+.PP
+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
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.PP
+POSIX.1 specifies
+.BR getrusage (),
+but specifies only the fields
+.I ru_utime
+and
+.IR ru_stime .
+.PP
+.B RUSAGE_THREAD
+is Linux-specific.
+.SH HISTORY
+POSIX.1-2001, SVr4, 4.3BSD.
+.PP
+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.
+.PP
+The structure definition shown at the start of this page
+was taken from 4.3BSD Reno.
+.PP
+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).
+.PP
+See also the description of
+.IR /proc/ pid /stat
+in
+.BR proc (5).
+.SH SEE ALSO
+.BR clock_gettime (2),
+.BR getrlimit (2),
+.BR times (2),
+.BR wait (2),
+.BR wait4 (2),
+.BR clock (3)