SYNOPSIS
        int *getrusage()

DESCRIPTION
        Return a array with current system resource usage statistics,
        namely: utime, stime, maxrss, rus.ru_ixrss, rus.ru_idrss,
                rus.ru_isrss, rus.ru_minflt, rus.ru_majflt, rus.ru_nswap,
                rus.ru_inblock, rus.ru_oublock, rus.ru_msgsnd,
                rus.ru_msgrcv, rus.ru_nsignals, rus.ru_nvcsw,
                rus.ru_nivcsw

        This function is optional.

	Contrary to rus.ru_maxrss, the 3rd value returned will not be in
	pages, but in bytes, since it is multiplied with the return value
	of the getpagesize() (Unix) system call.

SEE ALSO
        sys/resource.h (Unix)


(Unix) man page for getrusage:


GETRUSAGE(2)              SYSTEM CALLS               GETRUSAGE(2)



NAME
     getrusage - get information about resource utilization

SYNOPSIS
     #include <sys/time.h>
     #include <sys/resource.h>

     int getrusage(who, rusage)
     int who;
     struct rusage *rusage;

DESCRIPTION
     getrusage() returns information about the resources utilized
     by   the  current  process,  or  all  its  terminated  child
     processes.  The interpretation  for  some  values  reported,
     such  as ru_idrss, are dependent on the clock tick interval.
     This interval is  an  implementation  dependent  value;  for
     example,  on Sun-3 sytems the clock tick interval is 1/50 of
     a second, while on Sun-4 systems the clock tick interval  is
     1/100 of a second.

     The who parameter is one of RUSAGE_SELF or  RUSAGE_CHILDREN.
     The buffer to which rusage points will be filled in with the
     following structure:

          struct    rusage {
               struct timeval ru_utime;      /* user time used */
               struct timeval ru_stime;      /* system time used */
               int  ru_maxrss;          /* maximum resident set size */
               int  ru_ixrss;      /* currently 0 */
               int  ru_idrss;      /* integral resident set size */
               int  ru_isrss;      /* currently 0 */
               int  ru_minflt;          /* page faults not requiring physical I/O */
               int  ru_majflt;          /* page faults requiring physical I/O */
               int  ru_nswap;      /* swaps */
               int  ru_inblock;         /* block input operations */
               int  ru_oublock;         /* block output operations */
               int  ru_msgsnd;          /* messages sent */
               int  ru_msgrcv;          /* messages received */
               int  ru_nsignals;        /* signals received */
               int  ru_nvcsw;      /* voluntary context switches */
               int  ru_nivcsw;          /* involuntary context switches */
          };

     The fields are interpreted as follows:

     ru_utime       The total amount of time spent  executing  in
                    user  mode.   Time  is  given  in seconds and
                    microseconds.

     ru_stime       The total amount of time spent  executing  in
                    system  mode.   Time  is given in seconds and



Sun Release 4.1   Last change: 21 January 1990                  1






GETRUSAGE(2)              SYSTEM CALLS               GETRUSAGE(2)



                    microseconds.

     ru_maxrss      The maximum resident set size. Size is  given
                    in  pages  (the  size of a page, in bytes, is
                    given by  the  getpagesize(2)  system  call).
                    Also, see WARNINGS.

     ru_ixrss       Currently returns 0.

     ru_idrss       An "integral" value indicating the amount  of
                    memory  in use by a process while the process
                    is running.  This value is  the  sum  of  the
                    resident  set  sizes  of  the process running
                    when a clock tick occurs.  The value is given
                    in  pages  times  clock ticks.  Note: it does
                    not take sharing  into  account.   Also,  see
                    WARNINGS.

     ru_isrss       Currently returns 0.

     ru_minflt      The number of page faults serviced which  did
                    not require any physical I/O activity.  Also,
                    see WARNINGS.

     ru_majflt      The number  of  page  faults  serviced  which
                    required  physical  I/O activity.  This could
                    include page ahead operations by the  kernel.
                    Also, see WARNINGS.

     ru_nswap       The number of times a process was swapped out
                    of main memory.

     ru_inblock     The number of times the file  system  had  to
                    perform   input   in   servicing  a  read(2V)
                    request.

     ru_oublock     The number of times the file  system  had  to
                    perform   output  in  servicing  a  write(2V)
                    request.

     ru_msgsnd      The number of messages sent over sockets.

     ru_msgrcv      The number of messages received from sockets.

     ru_nsignals    The number of signals delivered.

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




Sun Release 4.1   Last change: 21 January 1990                  2






GETRUSAGE(2)              SYSTEM CALLS               GETRUSAGE(2)



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

RETURN VALUES
     getrusage() returns:

     0    on success.

     -1   on failure and sets errno to indicate the error.

ERRORS
     EFAULT         The address specified by the rusage  argument
                    is  not  in  a valid portion of the process's
                    address space.

     EINVAL         The who parameter is not a valid value.

SEE ALSO
     gettimeofday(2), read(2V), wait(2V), write(2V)

WARNINGS
     The numbers ru_inblock and ru_oublock account only for  real
     I/O, and are approximate measures at best.  Data supplied by
     the caching mechanism is charged only to the  first  process
     to read and the last process to write the data.

     The way resident set size is calculated is an approximation,
     and could misrepresent the true resident set size.

     Page faults can be generated from a variety of  sources  and
     for  a  variety  of reasons.  The customary cause for a page
     fault is a direct reference by the program to a  page  which
     is not in memory. Now, however, the kernel can generate page
     faults  on  behalf  of  the  user,  for  example,  servicing
     read(2V)  and write(2V) system calls. Also, a page fault can
     be caused by an absent hardware translation to a page,  even
     though the page is in physical memory.

     In addition to hardware detected page faults, the kernel may
     cause pseudo page faults in order to perform some housekeep-
     ing. For example, the kernel may generate page faults,  even
     if the pages exist in physical memory, in order to lock down
     pages involved in a raw I/O request.

     By definition, major page faults require physical I/O, while
     minor page faults do not require physical I/O.  For example,
     reclaiming the page from the free list would avoid  I/O  and
     generate  a  minor  page  fault.   More commonly, minor page
     faults occur during process startup as references  to  pages
     which  are  already  in  memory.  For example, if an address



Sun Release 4.1   Last change: 21 January 1990                  3






GETRUSAGE(2)              SYSTEM CALLS               GETRUSAGE(2)



     space faults on some "hot"  executable  or  shared  library,
     this  results  in  a minor page fault for the address space.
     Also, any one doing a read(2V)  or  write(2V)  to  something
     that  is in the page cache will get a minor page fault(s) as
     well.

BUGS
     There is no way to obtain information about a child  process
     which has not yet terminated.



Sun Release 4.1   Last change: 21 January 1990                  4
