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.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)profil.2 8.1 (Berkeley) 06/04/93 10.\" 11.Dd "" 12.Dt PROFIL 2 13.Os 14.Sh NAME 15.Nm profil 16.Nd control process profiling 17.Sh SYNOPSIS 18.Ft int 19.Fn profil "char *samples" "int size" "int offset" "int scale" 20.Sh DESCRIPTION 21The 22.Fn profil 23function enables or disables 24program counter profiling of the current process. 25If profiling is enabled, 26then at every clock tick, 27the kernel updates an appropriate count in the 28.Fa samples 29buffer. 30.Pp 31The buffer 32.Fa samples 33contains 34.Fa size 35bytes and is divided into 36a series of 16-bit bins. 37Each bin counts the number of times the program counter 38was in a particular address range in the process 39when a clock tick occurred while profiling was enabled. 40For a given program counter address, 41the number of the corresponding bin is given 42by the relation: 43.Bd -literal -offset indent 44[(pc - offset) / 2] * scale / 65536 45.Ed 46.Pp 47The 48.Fa offset 49parameter is the lowest address at which 50the kernel takes program counter samples. 51The 52.Fa scale 53parameter ranges from 1 to 65536 and 54can be used to change the span of the bins. 55A scale of 65536 maps each bin to 2 bytes of address range; 56a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. 57Intermediate values provide approximate intermediate ranges. 58A 59.Fa scale 60value of 0 disables profiling. 61.Sh RETURN VALUES 62If the 63.Fa scale 64value is nonzero and the buffer 65.Fa samples 66contains an illegal address, 67.Fn profil 68returns \-1, 69profiling is terminated and 70.Va errno 71is set appropriately. 72Otherwise 73.Fn profil 74returns 0. 75.Sh FILES 76.Bl -tag -width /usr/lib/gcrt0.o -compact 77.It Pa /usr/lib/gcrt0.o 78profiling C run-time startup file 79.It Pa gmon.out 80conventional name for profiling output file 81.El 82.Sh ERRORS 83The following error may be reported: 84.Bl -tag -width Er 85.It Bq Er EFAULT 86The buffer 87.Fa samples 88contains an invalid address. 89.El 90.Sh SEE ALSO 91.Xr gprof 1 92.\" .Sh HISTORY 93.\" wish I knew... probably v7. 94.Sh BUGS 95This routine should be named 96.Fn profile . 97.Pp 98The 99.Fa samples 100argument should really be a vector of type 101.Fa "unsigned short" . 102.Pp 103The format of the gmon.out file is undocumented. 104