bsd/man/man2/profil.2

   1 .\"     $NetBSD: profil.2,v 1.3 1995/11/22 23:07:23 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Donn Seeley of BSDI.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)profil.2    8.1 (Berkeley) 6/4/93
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt PROFIL 2
  41 .Os
  42 .Sh NAME
  43 .Nm profil
  44 .Nd control process profiling
  45 .Sh SYNOPSIS
  46 .Ft int
  47 .Fn profil "char *samples" "size_t size" "u_long offset" "u_int scale"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn profil
  51 function enables or disables
  52 program counter profiling of the current process.
  53 If profiling is enabled,
  54 then at every clock tick,
  55 the kernel updates an appropriate count in the
  56 .Fa samples
  57 buffer.
  58 .Pp
  59 The buffer
  60 .Fa samples
  61 contains
  62 .Fa size
  63 bytes and is divided into
  64 a series of 16-bit bins.
  65 Each bin counts the number of times the program counter
  66 was in a particular address range in the process
  67 when a clock tick occurred while profiling was enabled.
  68 For a given program counter address,
  69 the number of the corresponding bin is given
  70 by the relation:
  71 .Bd -literal -offset indent
  72 [(pc - offset) / 2] * scale / 65536
  73 .Ed
  74 .Pp
  75 The
  76 .Fa offset
  77 parameter is the lowest address at which
  78 the kernel takes program counter samples.
  79 The
  80 .Fa scale
  81 parameter ranges from 1 to 65536 and
  82 can be used to change the span of the bins.
  83 A scale of 65536 maps each bin to 2 bytes of address range;
  84 a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
  85 Intermediate values provide approximate intermediate ranges.
  86 A
  87 .Fa scale
  88 value of 0 disables profiling.
  89 .Sh RETURN VALUES
  90 If the
  91 .Fa scale
  92 value is nonzero and the buffer
  93 .Fa samples
  94 contains an illegal address,
  95 .Fn profil
  96 returns \-1,
  97 profiling is terminated and
  98 .Va errno
  99 is set appropriately.
 100 Otherwise
 101 .Fn profil
 102 returns 0.
 103 .Sh FILES
 104 .Bl -tag -width /usr/lib/gcrt0.o -compact
 105 .It Pa /usr/lib/gcrt0.o
 106 profiling C run-time startup file
 107 .It Pa gmon.out
 108 conventional name for profiling output file
 109 .El
 110 .Sh ERRORS
 111 The following error may be reported:
 112 .Bl -tag -width Er
 113 .It Bq Er EFAULT
 114 The buffer
 115 .Fa samples
 116 contains an invalid address.
 117 .El
 118 .Sh SEE ALSO
 119 .Xr gprof 1
 120 .\" .Sh HISTORY
 121 .\" wish I knew...  probably v7.
 122 .Sh BUGS
 123 This routine should be named
 124 .Fn profile .
 125 .Pp
 126 The
 127 .Fa samples
 128 argument should really be a vector of type
 129 .Fa "unsigned short" .
 130 .Pp
 131 The format of the gmon.out file is undocumented.