lib/libc/sys/profil.2

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Donn Seeley of BSDI.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 4. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)profil.2    8.1 (Berkeley) 6/4/93
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd June 4, 1993
  35 .Dt PROFIL 2
  36 .Os
  37 .Sh NAME
  38 .Nm profil
  39 .Nd control process profiling
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In unistd.h
  44 .Ft int
  45 .Fn profil "char *samples" "size_t size" "vm_offset_t offset" "int scale"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn profil
  49 system call enables or disables
  50 program counter profiling of the current process.
  51 If profiling is enabled,
  52 then at every profiling clock tick,
  53 the kernel updates an appropriate count in the
  54 .Fa samples
  55 buffer.
  56 The frequency of the profiling clock is recorded
  57 in the header in the profiling output file.
  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 profiling 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 argument is the lowest address at which
  78 the kernel takes program counter samples.
  79 The
  80 .Fa scale
  81 argument 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 .Rv -std profil
  91 .Sh FILES
  92 .Bl -tag -width /usr/lib/gcrt0.o -compact
  93 .It Pa /usr/lib/gcrt0.o
  94 profiling C run-time startup file
  95 .It Pa gmon.out
  96 conventional name for profiling output file
  97 .El
  98 .Sh ERRORS
  99 The following error may be reported:
 100 .Bl -tag -width Er
 101 .It Bq Er EFAULT
 102 The buffer
 103 .Fa samples
 104 contains an invalid address.
 105 .El
 106 .Sh SEE ALSO
 107 .Xr gprof 1
 108 .Sh HISTORY
 109 The
 110 .Fn profil
 111 function appeared in
 112 .At v7 .
 113 .Sh BUGS
 114 This routine should be named
 115 .Fn profile .
 116 .Pp
 117 The
 118 .Fa samples
 119 argument should really be a vector of type
 120 .Fa "unsigned short" .
 121 .Pp
 122 The format of the gmon.out file is undocumented.