lib/libc/sys/profil.2

   1 .\"     $NetBSD: profil.2,v 1.13 2003/08/07 16:44:04 agc 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. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)profil.2    8.1 (Berkeley) 6/4/93
  34 .\"
  35 .Dd June 4, 1993
  36 .Dt PROFIL 2
  37 .Os
  38 .Sh NAME
  39 .Nm profil
  40 .Nd control process profiling
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft int
  46 .Fn profil "char *samples" "size_t size" "u_long offset" "u_int scale"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn profil
  50 function enables or disables
  51 program counter profiling of the current process.
  52 If profiling is enabled,
  53 then at every clock tick,
  54 the kernel updates an appropriate count in the
  55 .Fa samples
  56 buffer.
  57 .Pp
  58 The buffer
  59 .Fa samples
  60 contains
  61 .Fa size
  62 bytes and is divided into
  63 a series of 16-bit bins.
  64 Each bin counts the number of times the program counter
  65 was in a particular address range in the process
  66 when a clock tick occurred while profiling was enabled.
  67 For a given program counter address,
  68 the number of the corresponding bin is given
  69 by the relation:
  70 .Bd -literal -offset indent
  71 [(pc - offset) / 2] * scale / 65536
  72 .Ed
  73 .Pp
  74 The
  75 .Fa offset
  76 parameter is the lowest address at which
  77 the kernel takes program counter samples.
  78 The
  79 .Fa scale
  80 parameter ranges from 1 to 65536 and
  81 can be used to change the span of the bins.
  82 A scale of 65536 maps each bin to 2 bytes of address range;
  83 a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
  84 Intermediate values provide approximate intermediate ranges.
  85 A
  86 .Fa scale
  87 value of 0 disables profiling.
  88 .Sh RETURN VALUES
  89 If the
  90 .Fa scale
  91 value is nonzero and the buffer
  92 .Fa samples
  93 contains an illegal address,
  94 .Fn profil
  95 returns \-1,
  96 profiling is terminated and
  97 .Va errno
  98 is set appropriately.
  99 Otherwise
 100 .Fn profil
 101 returns 0.
 102 .Sh FILES
 103 .Bl -tag -width /usr/lib/gcrt0.o -compact
 104 .It Pa /usr/lib/gcrt0.o
 105 profiling C run-time startup file
 106 .It Pa gmon.out
 107 conventional name for profiling output file.
 108 This may be different if the PROFDIR environment variable is set.
 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 .Xr moncontrol 3
 121 .\" .Sh HISTORY
 122 .\" wish I knew...  probably v7.
 123 .Sh BUGS
 124 This routine should be named
 125 .Fn profile .
 126 .Pp
 127 The
 128 .Fa samples
 129 argument should really be a vector of type
 130 .Fa "unsigned short" .
 131 .Pp
 132 The format of the gmon.out file is undocumented.