freebsd-dev/lib/libcompat/4.1/vtimes.3

.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)vtimes.3	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt VTIMES 3
.Os BSD 4
.Sh NAME
.Nm vtimes
.Nd get information about resource utilization
.Sh SYNOPSIS
.Fd #include <sys/vtimes.h>
.Fn vtimes "struct vtimes *par_vm" "struct vtimes *ch_vm"
.Sh DESCRIPTION
.Bf -symbolic
This interface is obsoleted by getrusage(2).
It is available from the compatibility library, libcompat.
.Ef
.Pp
The
.Fn vtimes
function
returns accounting information for the current process and for
the terminated child processes of the current
process.  Either
.Fa par_vm
or 
.Fa ch_vm
or both may be 0, in which case only the information for the pointers
which are non-zero is returned.
.Pp
After the call, each buffer contains information as defined by the
contents of the include file
.Pa /usr/include/sys/vtimes.h :
.Bd -literal -offset indent
struct vtimes {
	int	vm_utime;	/* user time (*HZ) */
	int	vm_stime;	/* system time (*HZ) */
	/* divide next two by utime+stime to get averages */
	unsigned vm_idsrss;	/* integral of d+s rss */
	unsigned vm_ixrss;	/* integral of text rss */
	int	vm_maxrss;	/* maximum rss */
	int	vm_majflt;	/* major page faults */
	int	vm_minflt;	/* minor page faults */
	int	vm_nswap;	/* number of swaps */
	int	vm_inblk;	/* block reads */
	int	vm_oublk;	/* block writes */
};
.Ed
.Pp
The
.Fa vm_utime
and
.Fa vm_stime
fields give the user and system
time respectively in 60ths of a second (or 50ths if that
is the frequency of wall current in your locality.) The
.Fa vm_idrss
and
.Fa vm_ixrss
measure memory usage.  They are computed by integrating the number of
memory pages in use each
over
.Tn CPU
time.  They are reported as though computed
discretely, adding the current memory usage (in 512 byte
pages) each time the clock ticks.  If a process used 5 core
pages over 1 cpu-second for its data and stack, then
.Fa vm_idsrss
would have the value 5*60, where
.Fa vm_utime+vm_stime
would be the 60.  
The
.Fa Vm_idsrss
argument
integrates data and stack segment
usage, while
.Fa vm_ixrss
integrates text segment usage.
The
.Fa Vm_maxrss
function
reports the maximum instantaneous sum of the
text+data+stack core-resident page count.
.Pp
The 
.Fa vm_majflt
field gives the number of page faults which
resulted in disk activity; the
.Fa vm_minflt
field gives the
number of page faults incurred in simulation of reference
bits;
.Fa vm_nswap
is the number of swaps which occurred.  The
number of file system input/output events are reported in
.Fa vm_inblk
and
.Fa vm_oublk
These numbers account only for real
.Tn I/O ;
data supplied by the caching mechanism is charged only
to the first process to read or write the data.
.Sh SEE ALSO
.Xr getrusage 2 ,
.Xr wait3 2 ,
.Xr time 3
.Sh HISTORY
The
.Fn vlimit
function appeared in 
.Bx 4.2 .
.Sh BUGS
This function has not yet been re-implemented.