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 LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In unistd.h
  49 .Ft int
  50 .Fn profil "char *samples" "size_t size" "u_long offset" "u_int scale"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn profil
  54 function enables or disables
  55 program counter profiling of the current process.
  56 If profiling is enabled,
  57 then at every clock tick,
  58 the kernel updates an appropriate count in the
  59 .Fa samples
  60 buffer.
  61 .Pp
  62 The buffer
  63 .Fa samples
  64 contains
  65 .Fa size
  66 bytes and is divided into
  67 a series of 16-bit bins.
  68 Each bin counts the number of times the program counter
  69 was in a particular address range in the process
  70 when a clock tick occurred while profiling was enabled.
  71 For a given program counter address,
  72 the number of the corresponding bin is given
  73 by the relation:
  74 .Bd -literal -offset indent
  75 [(pc - offset) / 2] * scale / 65536
  76 .Ed
  77 .Pp
  78 The
  79 .Fa offset
  80 parameter is the lowest address at which
  81 the kernel takes program counter samples.
  82 The
  83 .Fa scale
  84 parameter ranges from 1 to 65536 and
  85 can be used to change the span of the bins.
  86 A scale of 65536 maps each bin to 2 bytes of address range;
  87 a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
  88 Intermediate values provide approximate intermediate ranges.
  89 A
  90 .Fa scale
  91 value of 0 disables profiling.
  92 .Sh RETURN VALUES
  93 If the
  94 .Fa scale
  95 value is nonzero and the buffer
  96 .Fa samples
  97 contains an illegal address,
  98 .Fn profil
  99 returns \-1,
 100 profiling is terminated and
 101 .Va errno
 102 is set appropriately.
 103 Otherwise
 104 .Fn profil
 105 returns 0.
 106 .Sh FILES
 107 .Bl -tag -width /usr/lib/gcrt0.o -compact
 108 .It Pa /usr/lib/gcrt0.o
 109 profiling C run-time startup file
 110 .It Pa gmon.out
 111 conventional name for profiling output file
 112 .El
 113 .Sh ERRORS
 114 The following error may be reported:
 115 .Bl -tag -width Er
 116 .It Bq Er EFAULT
 117 The buffer
 118 .Fa samples
 119 contains an invalid address.
 120 .El
 121 .Sh SEE ALSO
 122 .Xr gprof 1
 123 .Sh HISTORY
 124 The
 125 .Fn profil
 126 function appeared in
 127 .At v7 .
 128 .Sh BUGS
 129 This routine should be named
 130 .Fn profile .
 131 .Pp
 132 The
 133 .Fa samples
 134 argument should really be a vector of type
 135 .Fa "unsigned short" .
 136 .Pp
 137 The format of the gmon.out file is undocumented.