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.\" @(#)profil.2 8.1 (Berkeley) 6/4/93 32.\" $FreeBSD: src/lib/libc/sys/profil.2,v 1.9.2.3 2001/12/14 18:34:01 ru Exp $ 33.\" 34.Dd October 6, 2019 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" "unsigned long offset" "unsigned int scale" 46.Sh DESCRIPTION 47The 48.Fn profil 49function enables or disables 50program counter profiling of the current process. 51If profiling is enabled, 52then at every profiling clock tick, 53the kernel updates an appropriate count in the 54.Fa samples 55buffer. 56The frequency of the profiling clock is recorded 57in the header in the profiling output file. 58.Pp 59The buffer 60.Fa samples 61contains 62.Fa size 63bytes and is divided into 64a series of 16-bit bins. 65Each bin counts the number of times the program counter 66was in a particular address range in the process 67when a profiling clock tick occurred while profiling was enabled. 68For a given program counter address, 69the number of the corresponding bin is given 70by the relation: 71.Bd -literal -offset indent 72[(pc - offset) / 2] * scale / 65536 73.Ed 74.Pp 75The 76.Fa offset 77parameter is the lowest address at which 78the kernel takes program counter samples. 79The 80.Fa scale 81parameter ranges from 1 to 65536 and 82can be used to change the span of the bins. 83A scale of 65536 maps each bin to 2 bytes of address range; 84a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. 85Intermediate values provide approximate intermediate ranges. 86A 87.Fa scale 88value 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 94profiling C run-time startup file 95.It Pa gmon.out 96conventional name for profiling output file 97.El 98.Sh ERRORS 99The following error may be reported: 100.Bl -tag -width Er 101.It Bq Er EFAULT 102The buffer 103.Fa samples 104contains an invalid address. 105.El 106.Sh SEE ALSO 107.Xr gprof 1 108.Sh HISTORY 109A 110.Fn profil 111function call appeared in 112.At v7 . 113.Sh BUGS 114This routine should be named 115.Fn profile . 116.Pp 117The 118.Fa samples 119argument should really be a vector of type 120.Fa "unsigned short" . 121.Pp 122The format of the gmon.out file is undocumented. 123