diff options
Diffstat (limited to 'man/man2/getrusage.2')
| -rw-r--r-- | man/man2/getrusage.2 | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/man/man2/getrusage.2 b/man/man2/getrusage.2 new file mode 100644 index 000000000..2ae9dafa4 --- /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 (date) "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) |