GNU Info

(libc.info)Resource Usage

---

Next: Limits on Resources Up: Resource Usage And Limitation

---

Enter node , (file) or (file)node

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)
     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.

     In the GNU system, you can also inquire about a particular child
     process by specifying its process ID.

     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.  Note: 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)
     `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'.