share/man/man3c/monitor.3c

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\"  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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MONITOR 3C "Dec 29, 1996"
   7 .SH NAME
   8 monitor \- prepare process execution profile
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <mon.h>
  13
  14 \fBvoid\fR \fBmonitor\fR(\fBint (*\fR\fIlowpc\fR(), \fBint (*\fR\fIhighpc\fR)(), \fBWORD *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR,
  15      \fBsize_t\fR \fInfunc\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBmonitor()\fR function is an interface to the \fBprofil\fR(2) function
  22 and is called automatically with default parameters by any program created by
  23 the \fBcc\fR utility with the \fB-p\fR option specified. Except to establish
  24 further control over profiling activity, it is not necessary to explicitly call
  25 \fBmonitor()\fR.
  26 .sp
  27 .LP
  28 When used, \fBmonitor()\fR is called at least at the beginning and the end of a
  29 program. The first call to \fBmonitor()\fR initiates the recording of two
  30 different kinds of execution-profile information: execution-time distribution
  31 and function call count. Execution-time distribution data is generated by
  32 \fBprofil()\fR and the function call counts are generated by code supplied to
  33 the object file (or files) by  \fBcc\fR \fB-p.\fR Both types of information are
  34 collected as a program executes. The last call to \fBmonitor()\fR writes this
  35 collected data to the output file \fBmon.out\fR.
  36 .sp
  37 .LP
  38 The name of the file written by \fBmonitor()\fR is controlled by the
  39 environment variable \fBPROFDIR\fR. If \fBPROFDIR\fR does not exist, the file
  40 \fBmon.out\fR is created in the current directory. If \fBPROFDIR\fR exists but
  41 has no value, \fBmonitor()\fR does no profiling and creates no output file. If
  42 \fBPROFDIR\fR is \fBdirname\fR, and \fBmonitor()\fR is called automatically by
  43 compilation with \fBcc \fR\fB-p\fR, the file created is
  44 \fBdirname\fR\fB/\fR\fIpid.progname\fR where \fIprogname\fR is the name of the
  45 program.
  46 .sp
  47 .LP
  48 The \fIlowpc\fR and \fIhighpc\fR arguments are the beginning and ending
  49 addresses of the region to be profiled.
  50 .sp
  51 .LP
  52 The \fIbuffer\fR argument is the address of a user-supplied array of \fBWORD\fR
  53 (defined in the header \fB<mon.h>\fR).  The \fIbuffer\fR argument is used by
  54 \fBmonitor()\fR to store the histogram generated by \fBprofil()\fR and the call
  55 counts.
  56 .sp
  57 .LP
  58 The \fIbufsize\fR argument identifies the number of array elements in
  59 \fIbuffer\fR.
  60 .sp
  61 .LP
  62 The \fInfunc\fR argument is the number of call count cells that have been
  63 reserved in \fIbuffer\fR. Additional call count cells will be allocated
  64 automatically as they are needed.
  65 .sp
  66 .LP
  67 The \fIbufsize\fR argument should be computed using the following formula:
  68 .sp
  69 .in +2
  70 .nf
  71 size_of_buffer =
  72         sizeof(struct hdr) +
  73         \fInfunc\fR * sizeof(struct cnt) +
  74         ((\fIhighpc\fR-\fIlowpc\fR)/\fIBARSIZE\fR) * sizeof(WORD) +
  75         sizeof(WORD) \(mi 1 ;
  76 bufsize = (size_of_buffer / sizeof(WORD));
  77 .fi
  78 .in -2
  79
  80 .sp
  81 .LP
  82 where:
  83 .RS +4
  84 .TP
  85 .ie t \(bu
  86 .el o
  87 \fIlowpc\fR, \fIhighpc\fR, \fInfunc\fR are the same as the arguments to
  88 \fBmonitor()\fR;
  89 .RE
  90 .RS +4
  91 .TP
  92 .ie t \(bu
  93 .el o
  94 \fIBARSIZE\fR is the number of program bytes that correspond to each histogram
  95 bar, or cell, of the \fBprofil()\fR buffer;
  96 .RE
  97 .RS +4
  98 .TP
  99 .ie t \(bu
 100 .el o
 101 the \fBhdr\fR and \fBcnt\fR structures and the type \fBWORD\fR are defined in
 102 the header \fB<mon.h>\fR\&.
 103 .RE
 104 .sp
 105 .LP
 106 The default call to \fBmonitor()\fR is as follows:
 107 .sp
 108 .in +2
 109 .nf
 110 monitor (&eprol, &etext, wbuf, wbufsz, 600);
 111 .fi
 112 .in -2
 113
 114 .sp
 115 .LP
 116 where:
 117 .RS +4
 118 .TP
 119 .ie t \(bu
 120 .el o
 121 \fBeprol\fR is the beginning of the user's program when linked with \fBcc
 122 \fR\fB-p\fR (see \fBend\fR(3C));
 123 .RE
 124 .RS +4
 125 .TP
 126 .ie t \(bu
 127 .el o
 128 \fBetext\fR is the end of the user's program (see \fBend\fR(3C));
 129 .RE
 130 .RS +4
 131 .TP
 132 .ie t \(bu
 133 .el o
 134 \fBwbuf\fR is an array of \fBWORD\fR with \fIwbufsz\fR elements;
 135 .RE
 136 .RS +4
 137 .TP
 138 .ie t \(bu
 139 .el o
 140 \fBwbufsz\fR is computed using the \fIbufsize\fR formula shown above with
 141 \fIBARSIZE\fR of 8;
 142 .RE
 143 .RS +4
 144 .TP
 145 .ie t \(bu
 146 .el o
 147 \fB600\fR is the number of call count cells that have been reserved in
 148 \fIbuffer\fR.
 149 .RE
 150 .sp
 151 .LP
 152 These parameter settings establish the computation of an execution-time
 153 distribution histogram that uses \fBprofil()\fR for the entire program,
 154 initially reserves room for 600 call count cells in \fIbuffer\fR, and provides
 155 for enough histogram cells to generate significant distribution-measurement
 156 results. For more information on the effects of \fIbufsize\fR on
 157 execution-distribution measurements, see \fBprofil\fR(2).
 158 .SH EXAMPLES
 159 .LP
 160 \fBExample 1 \fRExample to stop execution monitoring and write the results to a
 161 file.
 162 .sp
 163 .LP
 164 To stop execution monitoring and write the results to a file, use the
 165 following:
 166
 167 .sp
 168 .in +2
 169 .nf
 170 monitor(\|(int (*)(\|)\|)0, (int (*)(\|)\|)0, (WORD *)0, 0, 0);
 171 .fi
 172 .in -2
 173
 174 .sp
 175 .LP
 176 Use \fBprof\fR to examine the results.
 177
 178 .SH USAGE
 179 .sp
 180 .LP
 181 Additional calls to \fBmonitor()\fR after \fBmain()\fR has been called and
 182 before \fBexit()\fR has been called will add to the function-call count
 183 capacity, but such calls will also replace and restart the \fBprofil()\fR
 184 histogram computation.
 185 .SH ATTRIBUTES
 186 .sp
 187 .LP
 188 See \fBattributes\fR(5) for descriptions of the following attributes:
 189 .sp
 190
 191 .sp
 192 .TS
 193 box;
 194 c | c
 195 l | l .
 196 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 197 _
 198 MT-Level        Safe
 199 .TE
 200
 201 .SH SEE ALSO
 202 .sp
 203 .LP
 204 \fBprofil\fR(2), \fBend\fR(3C), \fBattributes\fR(5), \fBprof\fR(5)