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 .\" 3. 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 .Dd December 1, 2017
  32 .Dt PROFIL 2
  33 .Os
  34 .Sh NAME
  35 .Nm profil
  36 .Nd control process profiling
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In unistd.h
  41 .Ft int
  42 .Fn profil "char *samples" "size_t size" "vm_offset_t offset" "int scale"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn profil
  46 system call enables or disables
  47 program counter profiling of the current process.
  48 If profiling is enabled,
  49 then at every profiling clock tick,
  50 the kernel updates an appropriate count in the
  51 .Fa samples
  52 buffer.
  53 The frequency of the profiling clock is recorded
  54 in the header in the profiling output file.
  55 .Pp
  56 The buffer
  57 .Fa samples
  58 contains
  59 .Fa size
  60 bytes and is divided into
  61 a series of 16-bit bins.
  62 Each bin counts the number of times the program counter
  63 was in a particular address range in the process
  64 when a profiling clock tick occurred while profiling was enabled.
  65 For a given program counter address,
  66 the number of the corresponding bin is given
  67 by the relation:
  68 .Bd -literal -offset indent
  69 [(pc - offset) / 2] * scale / 65536
  70 .Ed
  71 .Pp
  72 The
  73 .Fa offset
  74 argument is the lowest address at which
  75 the kernel takes program counter samples.
  76 The
  77 .Fa scale
  78 argument ranges from 1 to 65536 and
  79 can be used to change the span of the bins.
  80 A scale of 65536 maps each bin to 2 bytes of address range;
  81 a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
  82 Intermediate values provide approximate intermediate ranges.
  83 A
  84 .Fa scale
  85 value of 0 disables profiling.
  86 .Sh RETURN VALUES
  87 .Rv -std profil
  88 .Sh FILES
  89 .Bl -tag -width /usr/lib/gcrt0.o -compact
  90 .It Pa /usr/lib/gcrt0.o
  91 profiling C run-time startup file
  92 .It Pa gmon.out
  93 conventional name for profiling output file
  94 .El
  95 .Sh ERRORS
  96 The following error may be reported:
  97 .Bl -tag -width Er
  98 .It Bq Er EFAULT
  99 The buffer
 100 .Fa samples
 101 contains an invalid address.
 102 .El
 103 .Sh SEE ALSO
 104 .Xr gprof 1
 105 .Sh HISTORY
 106 The
 107 .Fn profil
 108 functionality first appeared in
 109 .At v3 .
 110 .Sh BUGS
 111 This routine should be named
 112 .Fn profile .
 113 .Pp
 114 The
 115 .Fa samples
 116 argument should really be a vector of type
 117 .Fa "unsigned short" .
 118 .Pp
 119 The format of the gmon.out file is undocumented.