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