jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: profil.2,v 1.17 2025/07/13 23:38:55 jsg Exp $
2.\" $NetBSD: profil.2,v 1.3 1995/11/22 23:07:23 cgd Exp $
3.\"
4.\" Copyright (c) 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" This code is derived from software contributed to Berkeley by
8.\" Donn Seeley of BSDI.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\" 3. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)profil.2 8.1 (Berkeley) 6/4/93
35.\"
36.Dd $Mdocdate: July 13 2025 $
37.Dt PROFIL 2
38.Os
39.Sh NAME
40.Nm profil
41.Nd control process profiling
42.Sh SYNOPSIS
43.In unistd.h
44.Ft int
45.Fn profil "void *buf" "size_t buflen" "size_t samplesize" "u_long offset" "u_int scale" "int dirfd"
46.Sh DESCRIPTION
47The
48.Fn profil
49function is only available inside programs compiled with the
50.Fl pg
51compiler / linker option.
52.Fl pg
53selects the profiling version of the C-run-time code
54.Pa ( gcrt0.o ) ,
55which places an ELF note into the binary which enables the system call.
56The profiling subsystem only works with static binaries, so the
57.Fl static
58link option is also required.
59.Pp
60The first call to
61.Fn profil
62happens at startup inside
63.Pa gcrt0.o
64and sets up a region of memory
65.Fa buf
66that is
67.Fa buflen
68bytes long to contain a
69.Va struct gmonhdr ,
70a samples buffer of size
71.Fa samplesize ,
72and a sufficiently-sized arc-table.
73.Pp
74.Fa dirfd
75can indicate the path for placing the output file
76(environment variable
77.Ev PROFDIR
78is the usual choice).
79Otherwise, \-1 indicates the current (starting) directory location.
80.Pp
81Program execution then continues with profiling operational.
82During execution, profiling can be selectively stopped and restarted using
83.Xr moncontrol 3 .
84.Pp
85While profiling is enabled, at every clock tick, the kernel updates an
86appropriate count in the samples buffer.
87.Pp
88The samples buffer contains
89.Fa samplesize
90bytes and is divided into a series of 16-bit bins.
91Each bin counts the number of times the program counter was in a particular
92address range in the process when a clock tick occurred while profiling
93was enabled.
94For a given program counter address, the number of the corresponding bin
95is given by the relation:
96.Bd -literal -offset indent
97[(pc - offset) / 2] * scale / 65536
98.Ed
99.Pp
100The
101.Fa offset
102parameter is the lowest address at which the kernel takes program
103counter samples.
104The
105.Fa scale
106parameter ranges from 1 to 65536 and can be used to change the
107span of the bins.
108A scale of 65536 maps each bin to 2 bytes of address range;
109a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on.
110Intermediate values provide approximate intermediate ranges.
111A
112.Fa scale
113value of 0 disables profiling.
114.Pp
115At normal program termination, the C-run-time completes the data in the
116buffer to final format, and proceeds into
117.Xr _exit 2 .
118The kernel then constructs a pathname
119.Pa gmon.progname.pid.out
120and stores the data to the filesystem (either at the starting directory,
121or the optional directory indicated by the environment variable
122.Ev PROFDIR ) .
123.Pp
124Further processing is then done using
125.Xr gprof 1 .
126.Sh RETURN VALUES
127.Rv -std
128.Sh FILES
129.Bl -tag -width gmon.progname.pid.out -compact
130.It Pa /usr/lib/gcrt0.o
131profiling C run-time startup file
132.It Pa gmon.progname.pid.out
133conventional name for profiling output file
134.El
135.Sh ERRORS
136The following error may be reported:
137.Bl -tag -width Er
138.It Bq Er EPERM
139The program was not linked with
140.Fl pg .
141.It Bq Er EALREADY
142An attempt was made to change the profile buffer.
143.It Bq Er EBADF
144The
145.Fa dirfd
146argument is not a valid file descriptor.
147.It Bq Er ENOTDIR
148The
149.Fa dirfd
150argument does not refer to a directory.
151.It Bq Er EINVAL
152The
153.Fa scale
154value is too large.
155.El
156.Sh SEE ALSO
157.Xr gprof 1
158.Sh HISTORY
159The
160.Fn profil
161system call first appeared in
162.At v5 .
163.Pp
164Historically, profile information was written to the file by the C-run-time
165exit processing code using
166.Xr open 2 ,
167.Xr write 2 ,
168and such \(em which is incompatible with modern privilege separation practices
169like
170.Xr chroot 2 ,
171.Xr pledge 2 ,
172.Xr setresuid 2 ,
173and
174.Xr unveil 2 .
175This replacement
176.Fn profil
177interface was redesigned so the kernel writes out the profiling information
178on behalf of the terminating process.
179.Sh BUGS
180The
181.Fa samples
182argument should really be a vector of type
183.Fa "unsigned short" .