usr/src/man/man2/profil.2

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2001, 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PROFIL 2 "Nov 12, 2001"
   7 .SH NAME
   8 profil \- execution time profile
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <unistd.h>
  13
  14 \fBvoid\fR \fBprofil\fR(\fBunsigned short *\fR\fIbuff\fR, \fBunsigned int\fR \fIbufsiz\fR, \fBunsigned int\fR \fIoffset\fR,
  15      \fBunsigned int\fR \fIscale\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBprofil()\fR function provides CPU-use statistics by profiling the amount
  22 of \fBCPU\fR time expended by a program. The \fBprofil()\fR function generates
  23 the statistics by creating an execution histogram for a current process. The
  24 histogram is defined for a specific region of program code to be profiled, and
  25 the identified region is logically broken up into a set of equal size
  26 subdivisions, each of which corresponds to a count in the histogram.  With each
  27 clock tick, the current subdivision is identified and its corresponding
  28 histogram count is incremented. These counts establish a relative measure of
  29 how much time is being spent in each code subdivision.  The resulting histogram
  30 counts for a profiled region can be used to identify those functions that
  31 consume a disproportionately high percentage of \fBCPU\fR time.
  32 .sp
  33 .LP
  34 The \fIbuff\fR argument is a buffer of  \fIbufsiz\fR bytes in which the
  35 histogram counts are stored in an array of \fBunsigned short int\fR. Once one
  36 of the counts reaches 32767 (the size of a \fB short int\fR), profiling stops
  37 and no more data is collected.
  38 .sp
  39 .LP
  40 The \fIoffset\fR, \fIscale\fR, and  \fIbufsiz\fR arguments specify the region
  41 to be profiled.
  42 .sp
  43 .LP
  44 The \fIoffset\fR argument is effectively the start address of the region to be
  45 profiled.
  46 .sp
  47 .LP
  48 The \fIscale\fR argument is a contraction factor that indicates how much
  49 smaller the histogram buffer is than the region to be profiled. More precisely,
  50 \fIscale\fR is interpreted as an unsigned 16-bit fixed-point fraction with the
  51 decimal point implied on the left. Its value is the reciprocal of the number of
  52 bytes in a subdivision, per byte of histogram buffer. Since there are two bytes
  53 per histogram counter, the effective ratio of subdivision bytes per counter is
  54 one half the scale.
  55 .sp
  56 .LP
  57 The values of \fIscale\fR are as follows:
  58 .RS +4
  59 .TP
  60 .ie t \(bu
  61 .el o
  62 the maximum value of  \fIscale\fR, \fB0xffff\fR (approximately 1), maps
  63 subdivisions 2 bytes long to each counter.
  64 .RE
  65 .RS +4
  66 .TP
  67 .ie t \(bu
  68 .el o
  69 the minimum value of  \fIscale\fR (for which profiling is performed),
  70 \fB0x0002\fR (1/32,768), maps subdivision 65,536 bytes long to each counter.
  71 .RE
  72 .RS +4
  73 .TP
  74 .ie t \(bu
  75 .el o
  76 the default value of  \fIscale\fR (currently used by  \fBcc \fR\fB-qp\fR),
  77 \fB0x4000\fR, maps subdivisions 8 bytes long to each counter.
  78 .RE
  79 .sp
  80 .LP
  81 The values are used within the kernel as follows:  when the process is
  82 interrupted for a clock tick, the value of  \fIoffset\fR is subtracted from the
  83 current value of the program counter (pc), and the remainder is multiplied by
  84 \fIscale\fR to derive a result. That result is used as an index into the
  85 histogram array to locate the cell to be incremented. Therefore, the cell count
  86 represents the number of times that the process was executing code in the
  87 subdivision associated with that cell when the process was interrupted.
  88 .sp
  89 .LP
  90 The value of \fIscale\fR can be computed as  (\fIRATIO\fR \fB* 0200000L\fR),
  91 where \fIRATIO\fR is the desired ratio of  \fIbufsiz\fR to profiled region
  92 size, and has a value between 0 and 1. Qualitatively speaking, the closer
  93 \fIRATIO\fR is to 1, the higher the resolution of the profile information.
  94 .sp
  95 .LP
  96 The value of \fIbufsiz\fR can be computed as
  97 (\fIsize_of_region_to_be_profiled\fR \fB* \fR\fIRATIO\fR).
  98 .sp
  99 .LP
 100 Profiling is turned off by giving a \fIscale\fR value of 0 or 1, and is
 101 rendered ineffective by giving a \fIbufsiz\fR value of 0. Profiling is turned
 102 off when one of the \fBexec\fR family of functions (see \fBexec\fR(2)) is
 103 executed, but remains on in both child and parent  processes after a
 104 \fBfork\fR(2). Profiling is turned off if a \fIbuff\fR update would cause a
 105 memory fault.
 106 .SH USAGE
 107 .sp
 108 .LP
 109 The \fBpcsample\fR(2) function should be used when profiling dynamically-linked
 110 programs and 64-bit programs.
 111 .SH SEE ALSO
 112 .sp
 113 .LP
 114 \fBexec\fR(2), \fBfork\fR(2), \fBpcsample\fR(2), \fBtimes\fR(2),
 115 \fBmonitor\fR(3C), \fBprof\fR(5)
 116 .SH NOTES
 117 .sp
 118 .LP
 119 In Solaris releases prior to 2.6, calling \fBprofil()\fR in a multithreaded
 120 program would impact only the calling \fBLWP\fR; the profile state was not
 121 inherited at \fBLWP\fR creation time. To profile a multithreaded program with a
 122 global profile buffer, each thread needed to issue a call to \fBprofil()\fR at
 123 threads start-up time, and each thread had to be a bound thread. This was
 124 cumbersome and did not easily support dynamically turning profiling on and off.
 125 In Solaris 2.6, the \fBprofil()\fR system call for multithreaded processes has
 126 global impact \(em that is, a call to \fBprofil()\fR impacts all
 127 \fBLWP\fRs/threads in the process. This may cause applications that depend on
 128 the previous per-\fBLWP\fR semantic to break, but it is expected to improve
 129 multithreaded programs that wish to turn profiling on and off dynamically at
 130 runtime.