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