1*61183Sbostic.\" Copyright (c) 1993 2*61183Sbostic.\" The Regents of the University of California. All rights reserved. 320041Smckusick.\" 458394Sbostic.\" This code is derived from software contributed to Berkeley by 558394Sbostic.\" Donn Seeley of BSDI. 620041Smckusick.\" 758394Sbostic.\" %sccs.include.redist.roff% 848837Scael.\" 9*61183Sbostic.\" @(#)profil.2 8.1 (Berkeley) 06/04/93 1058394Sbostic.\" 1158394Sbostic.Dd "" 1258394Sbostic.Dt PROFIL 2 1358394Sbostic.Os 1458394Sbostic.Sh NAME 1558394Sbostic.Nm profil 1658394Sbostic.Nd control process profiling 1758394Sbostic.Sh SYNOPSIS 1858394Sbostic.Ft int 1958394Sbostic.Fn profil "char *samples" "int size" "int offset" "int scale" 2058394Sbostic.Sh DESCRIPTION 2158394SbosticThe 2258394Sbostic.Fn profil 2358394Sbosticfunction enables or disables 2458394Sbosticprogram counter profiling of the current process. 2558394SbosticIf profiling is enabled, 2658394Sbosticthen at every clock tick, 2758394Sbosticthe kernel updates an appropriate count in the 2858394Sbostic.Fa samples 2958394Sbosticbuffer. 3058394Sbostic.Pp 3158394SbosticThe buffer 3258394Sbostic.Fa samples 3358394Sbosticcontains 3458394Sbostic.Fa size 3558394Sbosticbytes and is divided into 3658394Sbostica series of 16-bit bins. 3758394SbosticEach bin counts the number of times the program counter 3858394Sbosticwas in a particular address range in the process 3958394Sbosticwhen a clock tick occurred while profiling was enabled. 4058394SbosticFor a given program counter address, 4158394Sbosticthe number of the corresponding bin is given 4258394Sbosticby the relation: 4358394Sbostic.Bd -literal -offset indent 4458394Sbostic[(pc - offset) / 2] * scale / 65536 4558394Sbostic.Ed 4658394Sbostic.Pp 4758394SbosticThe 4858394Sbostic.Fa offset 4958394Sbosticparameter is the lowest address at which 5058394Sbosticthe kernel takes program counter samples. 5158394SbosticThe 5258394Sbostic.Fa scale 5358394Sbosticparameter ranges from 1 to 65536 and 5458394Sbosticcan be used to change the span of the bins. 5558394SbosticA scale of 65536 maps each bin to 2 bytes of address range; 5658394Sbostica scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. 5758394SbosticIntermediate values provide approximate intermediate ranges. 5858394SbosticA 5958394Sbostic.Fa scale 6058394Sbosticvalue of 0 disables profiling. 6158394Sbostic.Sh RETURN VALUES 6258394SbosticIf the 6358394Sbostic.Fa scale 6458394Sbosticvalue is nonzero and the buffer 6558394Sbostic.Fa samples 6658394Sbosticcontains an illegal address, 6758394Sbostic.Fn profil 6858394Sbosticreturns \-1, 6958394Sbosticprofiling is terminated and 7058394Sbostic.Va errno 7158394Sbosticis set appropriately. 7258394SbosticOtherwise 7358394Sbostic.Fn profil 7458394Sbosticreturns 0. 7558394Sbostic.Sh FILES 7658394Sbostic.Bl -tag -width /usr/lib/gcrt0.o -compact 7758394Sbostic.It Pa /usr/lib/gcrt0.o 7858394Sbosticprofiling C run-time startup file 7958394Sbostic.It Pa gmon.out 8058394Sbosticconventional name for profiling output file 8158394Sbostic.El 8258394Sbostic.Sh ERRORS 8358394SbosticThe following error may be reported: 8458394Sbostic.Bl -tag -width Er 8558394Sbostic.It Bq Er EFAULT 8658394SbosticThe buffer 8758394Sbostic.Fa samples 8858394Sbosticcontains an invalid address. 8958394Sbostic.El 9058394Sbostic.Sh SEE ALSO 9158394Sbostic.Xr gprof 1 9258394Sbostic.\" .Sh HISTORY 9358394Sbostic.\" wish I knew... probably v7. 9458394Sbostic.Sh BUGS 9558394SbosticThis routine should be named 9658394Sbostic.Fn profile . 9758394Sbostic.Pp 9858394SbosticThe 9958394Sbostic.Fa samples 10058394Sbosticargument should really be a vector of type 10158394Sbostic.Fa "unsigned short" . 10258394Sbostic.Pp 10358394SbosticThe format of the gmon.out file is undocumented. 104