[apple/xnu.git] / bsd / man / man2 / profil.2

.\"	$NetBSD: profil.2,v 1.3 1995/11/22 23:07:23 cgd Exp $
.\"
.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Donn Seeley of BSDI.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)profil.2	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt PROFIL 2
.Os
.Sh NAME
.Nm profil
.Nd control process profiling
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn profil "char *samples" "size_t size" "u_long offset" "u_int scale"
.Sh DESCRIPTION
The
.Fn profil
function enables or disables
program counter profiling of the current process.
If profiling is enabled,
then at every clock tick,
the kernel updates an appropriate count in the
.Fa samples
buffer.
.Pp
The buffer
.Fa samples
contains
.Fa size
bytes and is divided into
a series of 16-bit bins.
Each bin counts the number of times the program counter
was in a particular address range in the process
when a clock tick occurred while profiling was enabled.
For a given program counter address,
the number of the corresponding bin is given
by the relation:
.Bd -literal -offset indent
[(pc - offset) / 2] * scale / 65536
.Ed
.Pp
The
.Fa offset
parameter is the lowest address at which
the kernel takes program counter samples.
The
.Fa scale
parameter ranges from 1 to 65536 and
can be used to change the span of the bins.
A scale of 65536 maps each bin to 2 bytes of address range;
a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
Intermediate values provide approximate intermediate ranges.
A
.Fa scale
value of 0 disables profiling.
.Sh RETURN VALUES
If the
.Fa scale
value is nonzero and the buffer
.Fa samples
contains an illegal address,
.Fn profil
returns \-1,
profiling is terminated and
.Va errno
is set appropriately.
Otherwise
.Fn profil
returns 0.
.Sh FILES
.Bl -tag -width /usr/lib/gcrt0.o -compact
.It Pa /usr/lib/gcrt0.o
profiling C run-time startup file
.It Pa gmon.out
conventional name for profiling output file
.El
.Sh ERRORS
The following error may be reported:
.Bl -tag -width Er
.It Bq Er EFAULT
The buffer
.Fa samples
contains an invalid address.
.El
.Sh SEE ALSO
.Xr gprof 1
.Sh HISTORY
The
.Fn profil
function appeared in
.At v7 .
.Sh BUGS
This routine should be named
.Fn profile .
.Pp
The
.Fa samples
argument should really be a vector of type
.Fa "unsigned short" .
.Pp
The format of the gmon.out file is undocumented.
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: profil.2,v 1.3 1995/11/22 23:07:23 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" This code is derived from software contributed to Berkeley by
	7	.\" Donn Seeley of BSDI.
	8	.\"
	9	.\" Redistribution and use in source and binary forms, with or without
	10	.\" modification, are permitted provided that the following conditions
	11	.\" are met:
	12	.\" 1. Redistributions of source code must retain the above copyright
	13	.\" notice, this list of conditions and the following disclaimer.
	14	.\" 2. Redistributions in binary form must reproduce the above copyright
	15	.\" notice, this list of conditions and the following disclaimer in the
	16	.\" documentation and/or other materials provided with the distribution.
	17	.\" 3. All advertising materials mentioning features or use of this software
	18	.\" must display the following acknowledgement:
	19	.\" This product includes software developed by the University of
	20	.\" California, Berkeley and its contributors.
	21	.\" 4. Neither the name of the University nor the names of its contributors
	22	.\" may be used to endorse or promote products derived from this software
	23	.\" without specific prior written permission.
	24	.\"
	25	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	26	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	27	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	28	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	29	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	30	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	31	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	32	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	33	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	34	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	35	.\" SUCH DAMAGE.
	36	.\"
	37	.\" @(#)profil.2 8.1 (Berkeley) 6/4/93
	38	.\"
	39	.Dd June 4, 1993
	40	.Dt PROFIL 2
	41	.Os
	42	.Sh NAME
	43	.Nm profil
	44	.Nd control process profiling
2d21ac55 A	45	.Sh LIBRARY
2d21ac55 A	46	.Lb libc
9bccf70c	47	.Sh SYNOPSIS
2d21ac55	48	.In unistd.h
9bccf70c A	49	.Ft int
	50	.Fn profil "char *samples" "size_t size" "u_long offset" "u_int scale"
	51	.Sh DESCRIPTION
	52	The
	53	.Fn profil
	54	function enables or disables
	55	program counter profiling of the current process.
	56	If profiling is enabled,
	57	then at every clock tick,
	58	the kernel updates an appropriate count in the
	59	.Fa samples
	60	buffer.
	61	.Pp
	62	The buffer
	63	.Fa samples
	64	contains
	65	.Fa size
	66	bytes and is divided into
	67	a series of 16-bit bins.
	68	Each bin counts the number of times the program counter
	69	was in a particular address range in the process
	70	when a clock tick occurred while profiling was enabled.
	71	For a given program counter address,
	72	the number of the corresponding bin is given
	73	by the relation:
	74	.Bd -literal -offset indent
	75	[(pc - offset) / 2] * scale / 65536
	76	.Ed
	77	.Pp
	78	The
	79	.Fa offset
	80	parameter is the lowest address at which
	81	the kernel takes program counter samples.
	82	The
	83	.Fa scale
	84	parameter ranges from 1 to 65536 and
	85	can be used to change the span of the bins.
	86	A scale of 65536 maps each bin to 2 bytes of address range;
	87	a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
	88	Intermediate values provide approximate intermediate ranges.
	89	A
	90	.Fa scale
	91	value of 0 disables profiling.
	92	.Sh RETURN VALUES
	93	If the
	94	.Fa scale
	95	value is nonzero and the buffer
	96	.Fa samples
	97	contains an illegal address,
	98	.Fn profil
	99	returns \-1,
	100	profiling is terminated and
	101	.Va errno
	102	is set appropriately.
	103	Otherwise
	104	.Fn profil
	105	returns 0.
	106	.Sh FILES
	107	.Bl -tag -width /usr/lib/gcrt0.o -compact
	108	.It Pa /usr/lib/gcrt0.o
	109	profiling C run-time startup file
	110	.It Pa gmon.out
	111	conventional name for profiling output file
	112	.El
113	.Sh ERRORS
114	The following error may be reported:
115	.Bl -tag -width Er
116	.It Bq Er EFAULT
117	The buffer
118	.Fa samples
119	contains an invalid address.
120	.El
121	.Sh SEE ALSO
122	.Xr gprof 1
2d21ac55 A	123	.Sh HISTORY
	124	The
	125	.Fn profil
	126	function appeared in
	127	.At v7 .
9bccf70c A	128	.Sh BUGS
	129	This routine should be named
	130	.Fn profile .
	131	.Pp
	132	The
	133	.Fa samples
	134	argument should really be a vector of type
	135	.Fa "unsigned short" .
	136	.Pp
	137	The format of the gmon.out file is undocumented.