getrusage(3C)						   Standard C Library Functions 					     getrusage(3C)

NAME

       getrusage - get information about resource utilization

SYNOPSIS

       #include <sys/resource.h>

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

DESCRIPTION

       The  getrusage() function provides measures of the resources used by the current process, its terminated and waited-for child processes, or
       the current light weight process (LWP).	If the value of the who argument is RUSAGE_SELF, information is returned about resources  used	by
       the  current  process.  If the value of the who argument is RUSAGE_CHILDREN, information is returned about resources used by the terminated
       and waited-for children of the current process. If the child is never waited for (for instance, if the parent has SA_NOCLDWAIT set or  sets
       SIGCHLD	to  SIG_IGN), the resource information for the child process is discarded and not included in the resource information provided by
       getrusage(). If the value of the who argument is RUSAGE_LWP, information is returned about resources used by the current LWP.

       The r_usage argument is a pointer to an object of type struct rusage in which the returned information is stored.  The  members	of  rusage
       are as follows:

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

       The structure members 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 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(3C) func-
		      tion). See the NOTES section of this page.

       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. It
		      does not take sharing into account. See the  NOTES section of this page.

       ru_minflt      The number of page faults serviced which did not require any physical I/O activity. See the  NOTES section of this page.

       ru_majflt      The number of page faults serviced which required physical I/O activity. This could include page	ahead  operations  by  the
		      kernel. See the  NOTES section of this page.

       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(2) request.

       ru_oublock     The number of times the file system had to perform output in servicing a write(2) 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).

       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

       Upon successful completion, getrusage() returns 0. Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

       The  getrusage() function will fail if:

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

       EINVAL	 The who parameter is not a valid value.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |ATTRIBUTE TYPE		     |ATTRIBUTE VALUE		   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       sar(1M), read(2), times(2), write(2), getpagesize(3C), gettimeofday(3C), wait(3C), attributes(5), standards(5)

NOTES

       The ru_maxrss, ru_ixrss, ru_idrss, and ru_isrss members of the rusage structure are set to 0 in this implementation.

       The numbers ru_inblock and ru_oublock account only for real I/O, and are approximate measures at best. Data supplied by the cache 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  ref-
       erence 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 exam-
       ple, servicing read(2) and write(2) functions. 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 housekeeping.  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 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(2) or write(2) to something that is in the page cache will
       get a minor page fault(s) as well.

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

SunOS 5.11							    2 Jul 2004							     getrusage(3C)