[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 SYNOPSIS
.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
.\" wish I knew...  probably 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
	45	.Sh SYNOPSIS
	46	.Ft int
	47	.Fn profil "char *samples" "size_t size" "u_long offset" "u_int scale"
	48	.Sh DESCRIPTION
	49	The
	50	.Fn profil
	51	function enables or disables
	52	program counter profiling of the current process.
	53	If profiling is enabled,
	54	then at every clock tick,
	55	the kernel updates an appropriate count in the
	56	.Fa samples
	57	buffer.
	58	.Pp
	59	The buffer
	60	.Fa samples
	61	contains
	62	.Fa size
	63	bytes and is divided into
	64	a series of 16-bit bins.
65	Each bin counts the number of times the program counter
66	was in a particular address range in the process
67	when a clock tick occurred while profiling was enabled.
68	For a given program counter address,
69	the number of the corresponding bin is given
70	by the relation:
71	.Bd -literal -offset indent
72	[(pc - offset) / 2] * scale / 65536
73	.Ed
74	.Pp
75	The
76	.Fa offset
77	parameter is the lowest address at which
78	the kernel takes program counter samples.
79	The
80	.Fa scale
81	parameter ranges from 1 to 65536 and
82	can be used to change the span of the bins.
83	A scale of 65536 maps each bin to 2 bytes of address range;
84	a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
85	Intermediate values provide approximate intermediate ranges.
86	A
87	.Fa scale
88	value of 0 disables profiling.
89	.Sh RETURN VALUES
90	If the
91	.Fa scale
92	value is nonzero and the buffer
93	.Fa samples
94	contains an illegal address,
95	.Fn profil
96	returns \-1,
97	profiling is terminated and
98	.Va errno
99	is set appropriately.
100	Otherwise
101	.Fn profil
102	returns 0.
103	.Sh FILES
104	.Bl -tag -width /usr/lib/gcrt0.o -compact
105	.It Pa /usr/lib/gcrt0.o
106	profiling C run-time startup file
107	.It Pa gmon.out
108	conventional name for profiling output file
109	.El
110	.Sh ERRORS
111	The following error may be reported:
112	.Bl -tag -width Er
113	.It Bq Er EFAULT
114	The buffer
115	.Fa samples
116	contains an invalid address.
117	.El
118	.Sh SEE ALSO
119	.Xr gprof 1
120	.\" .Sh HISTORY
121	.\" wish I knew... probably v7.
122	.Sh BUGS
123	This routine should be named
124	.Fn profile .
125	.Pp
126	The
127	.Fa samples
128	argument should really be a vector of type
129	.Fa "unsigned short" .
130	.Pp
131	The format of the gmon.out file is undocumented.