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