### 22.1 Resource Usage

The function `getrusage` and the data type `struct rusage` are used to examine the resource usage of a process. They are declared in `sys/resource.h`.

— Function: int getrusage (int processes, struct rusage *rusage)

> Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

> This function reports resource usage totals for processes specified by processes, storing the information in `*`rusage.

> In most systems, processes has only two valid values:

> `RUSAGE_SELF`
>   Just the current process.
> `RUSAGE_CHILDREN`
>   All child processes (direct and indirect) that have already terminated.

> The return value of `getrusage` is zero for success, and `-1` for failure.

> `EINVAL`
>   The argument processes is not valid.

One way of getting resource usage for a particular child process is with the function `wait4`, which returns totals for a child when it terminates. See BSD Wait Functions.

— Data Type: struct rusage

> This data type stores various resource usage statistics. It has the following members, and possibly others:

> `struct timeval ru_utime`
>   Time spent executing user instructions.
> `struct timeval ru_stime`
>   Time spent in operating system code on behalf of processes.
> `long int ru_maxrss`
>   The maximum resident set size used, in kilobytes. That is, the maximum number of kilobytes of physical memory that processes used simultaneously.
> `long int ru_ixrss`
>   An integral value expressed in kilobytes times ticks of execution, which indicates the amount of memory used by text that was shared with other processes.
> `long int ru_idrss`
>   An integral value expressed the same way, which is the amount of unshared memory used for data.
> `long int ru_isrss`
>   An integral value expressed the same way, which is the amount of unshared memory used for stack space.
> `long int ru_minflt`
>   The number of page faults which were serviced without requiring any I/O.
> `long int ru_majflt`
>   The number of page faults which were serviced by doing I/O.
> `long int ru_nswap`
>   The number of times processes was swapped entirely out of main memory.
> `long int ru_inblock`
>   The number of times the file system had to read from the disk on behalf of processes.
> `long int ru_oublock`
>   The number of times the file system had to write to the disk on behalf of processes.
> `long int ru_msgsnd`
>   Number of IPC messages sent.
> `long int ru_msgrcv`
>   Number of IPC messages received.
> `long int ru_nsignals`
>   Number of signals received.
> `long int ru_nvcsw`
>   The number of times processes voluntarily invoked a context switch (usually to wait for some service).
> `long int ru_nivcsw`
>   The number of times an involuntary context switch took place (because a time slice expired, or another process of higher priority was scheduled).

`vtimes` is a historical function that does some of what `getrusage` does. `getrusage` is a better choice.

`vtimes` and its `vtimes` data structure are declared in `sys/vtimes.h`.

— Function: int vtimes (struct vtimes *current, struct vtimes *child)

> Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

> `vtimes` reports resource usage totals for a process.

> If current is non-null, `vtimes` stores resource usage totals for the invoking process alone in the structure to which it points. If child is non-null, `vtimes` stores resource usage totals for all past children (which have terminated) of the invoking process in the structure to which it points.

> — Data Type: struct vtimes

> > This data type contains information about the resource usage of a process. Each member corresponds to a member of the `struct rusage` data type described above.

> > `vm_utime`
> >   User CPU time. Analogous to `ru_utime` in `struct rusage`
> > `vm_stime`
> >   System CPU time. Analogous to `ru_stime` in `struct rusage`
> > `vm_idsrss`
> >   Data and stack memory. The sum of the values that would be reported as `ru_idrss` and `ru_isrss` in `struct rusage`
> > `vm_ixrss`
> >   Shared memory. Analogous to `ru_ixrss` in `struct rusage`
> > `vm_maxrss`
> >   Maximent resident set size. Analogous to `ru_maxrss` in `struct rusage`
> > `vm_majflt`
> >   Major page faults. Analogous to `ru_majflt` in `struct rusage`
> > `vm_minflt`
> >   Minor page faults. Analogous to `ru_minflt` in `struct rusage`
> > `vm_nswap`
> >   Swap count. Analogous to `ru_nswap` in `struct rusage`
> > `vm_inblk`
> >   Disk reads. Analogous to `ru_inblk` in `struct rusage`
> > `vm_oublk`
> >   Disk writes. Analogous to `ru_oublk` in `struct rusage`

> The return value is zero if the function succeeds; `-1` otherwise.

An additional historical function for examining resource usage, `vtimes`, is supported but not documented here. It is declared in `sys/vtimes.h`.