'\" te .\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH MONITOR 3C "Dec 29, 1996" .SH NAME monitor \- prepare process execution profile .SH SYNOPSIS .LP .nf #include \fBvoid\fR \fBmonitor\fR(\fBint (*\fR\fIlowpc\fR(), \fBint (*\fR\fIhighpc\fR)(), \fBWORD *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR, \fBsize_t\fR \fInfunc\fR); .fi .SH DESCRIPTION .sp .LP The \fBmonitor()\fR function is an interface to the \fBprofil\fR(2) function and is called automatically with default parameters by any program created by the \fBcc\fR utility with the \fB-p\fR option specified. Except to establish further control over profiling activity, it is not necessary to explicitly call \fBmonitor()\fR. .sp .LP When used, \fBmonitor()\fR is called at least at the beginning and the end of a program. The first call to \fBmonitor()\fR initiates the recording of two different kinds of execution-profile information: execution-time distribution and function call count. Execution-time distribution data is generated by \fBprofil()\fR and the function call counts are generated by code supplied to the object file (or files) by \fBcc\fR \fB-p.\fR Both types of information are collected as a program executes. The last call to \fBmonitor()\fR writes this collected data to the output file \fBmon.out\fR. .sp .LP The name of the file written by \fBmonitor()\fR is controlled by the environment variable \fBPROFDIR\fR. If \fBPROFDIR\fR does not exist, the file \fBmon.out\fR is created in the current directory. If \fBPROFDIR\fR exists but has no value, \fBmonitor()\fR does no profiling and creates no output file. If \fBPROFDIR\fR is \fBdirname\fR, and \fBmonitor()\fR is called automatically by compilation with \fBcc \fR\fB-p\fR, the file created is \fBdirname\fR\fB/\fR\fIpid.progname\fR where \fIprogname\fR is the name of the program. .sp .LP The \fIlowpc\fR and \fIhighpc\fR arguments are the beginning and ending addresses of the region to be profiled. .sp .LP The \fIbuffer\fR argument is the address of a user-supplied array of \fBWORD\fR (defined in the header \fB\fR). The \fIbuffer\fR argument is used by \fBmonitor()\fR to store the histogram generated by \fBprofil()\fR and the call counts. .sp .LP The \fIbufsize\fR argument identifies the number of array elements in \fIbuffer\fR. .sp .LP The \fInfunc\fR argument is the number of call count cells that have been reserved in \fIbuffer\fR. Additional call count cells will be allocated automatically as they are needed. .sp .LP The \fIbufsize\fR argument should be computed using the following formula: .sp .in +2 .nf size_of_buffer = sizeof(struct hdr) + \fInfunc\fR * sizeof(struct cnt) + ((\fIhighpc\fR-\fIlowpc\fR)/\fIBARSIZE\fR) * sizeof(WORD) + sizeof(WORD) \(mi 1 ; bufsize = (size_of_buffer / sizeof(WORD)); .fi .in -2 .sp .LP where: .RS +4 .TP .ie t \(bu .el o \fIlowpc\fR, \fIhighpc\fR, \fInfunc\fR are the same as the arguments to \fBmonitor()\fR; .RE .RS +4 .TP .ie t \(bu .el o \fIBARSIZE\fR is the number of program bytes that correspond to each histogram bar, or cell, of the \fBprofil()\fR buffer; .RE .RS +4 .TP .ie t \(bu .el o the \fBhdr\fR and \fBcnt\fR structures and the type \fBWORD\fR are defined in the header \fB\fR\&. .RE .sp .LP The default call to \fBmonitor()\fR is as follows: .sp .in +2 .nf monitor (&eprol, &etext, wbuf, wbufsz, 600); .fi .in -2 .sp .LP where: .RS +4 .TP .ie t \(bu .el o \fBeprol\fR is the beginning of the user's program when linked with \fBcc \fR\fB-p\fR (see \fBend\fR(3C)); .RE .RS +4 .TP .ie t \(bu .el o \fBetext\fR is the end of the user's program (see \fBend\fR(3C)); .RE .RS +4 .TP .ie t \(bu .el o \fBwbuf\fR is an array of \fBWORD\fR with \fIwbufsz\fR elements; .RE .RS +4 .TP .ie t \(bu .el o \fBwbufsz\fR is computed using the \fIbufsize\fR formula shown above with \fIBARSIZE\fR of 8; .RE .RS +4 .TP .ie t \(bu .el o \fB600\fR is the number of call count cells that have been reserved in \fIbuffer\fR. .RE .sp .LP These parameter settings establish the computation of an execution-time distribution histogram that uses \fBprofil()\fR for the entire program, initially reserves room for 600 call count cells in \fIbuffer\fR, and provides for enough histogram cells to generate significant distribution-measurement results. For more information on the effects of \fIbufsize\fR on execution-distribution measurements, see \fBprofil\fR(2). .SH EXAMPLES .LP \fBExample 1 \fRExample to stop execution monitoring and write the results to a file. .sp .LP To stop execution monitoring and write the results to a file, use the following: .sp .in +2 .nf monitor(\|(int (*)(\|)\|)0, (int (*)(\|)\|)0, (WORD *)0, 0, 0); .fi .in -2 .sp .LP Use \fBprof\fR to examine the results. .SH USAGE .sp .LP Additional calls to \fBmonitor()\fR after \fBmain()\fR has been called and before \fBexit()\fR has been called will add to the function-call count capacity, but such calls will also replace and restart the \fBprofil()\fR histogram computation. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ MT-Level Safe .TE .SH SEE ALSO .sp .LP \fBprofil\fR(2), \fBend\fR(3C), \fBattributes\fR(5), \fBprof\fR(5)