.\"	$NetBSD: tprof.8,v 1.3 2011/12/09 15:26:48 yamt Exp $
.\"
.\" Copyright (c)2011 YAMAMOTO Takashi,
.\" All rights reserved.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" ------------------------------------------------------------
.Dd November 26, 2011
.Dt TPROF 8
.Os
.\" ------------------------------------------------------------
.Sh NAME
.Nm tprof
.Nd record tprof profiling samples
.\" ------------------------------------------------------------
.Sh SYNOPSIS
.Nm
.Op Fl c
.Op Fl o Ar file
.Ar command ...
.\" ------------------------------------------------------------
.Sh DESCRIPTION
The
.Nm
is a sampling based profiler.
.Pp
.Nm
utility makes the kernel driver start profiling,
executes the specified command,
keeps recording samples from the kernel driver until the command finishes,
and reports statistics to the standard error.
.Pp
The
.Nm tprof
pseudo driver and a suitable backend should be loaded beforehand.
.Pp
The
.Nm
utility accepts the following options.
.Bl -tag -width hogehoge
.It Fl o Ar file
Write the collected samples to the file named
.Ar file .
The default is
.Dq Pa tprof.out .
.It Fl c
Write the collected samples to the standard output.
Note that the output is a binary stream.
.El
.\" ------------------------------------------------------------
.Sh EXAMPLES
The following command profiles the system during 1 second and shows
the top-10 kernel functions which likely consumed CPU cycles.
.Bd -literal
	tprof -c sleep 1 2>/dev/null | tpfmt -skCLP | head -10
.Ed
.\" ------------------------------------------------------------
.Sh DIAGNOSTICS
The
.Nm
utility reports the following statistics about the activities of the
.Nm tprof
pseudo driver.
.Bl -tag -width dropbuf_samples
.It sample
The number of samples collected and prepared for userland consumption.
.It overflow
The number of samples dropped because the per-CPU buffer was full.
.It buf
The number of buffers successfully prepared for userland consumption.
.It emptybuf
The number of buffers which have been dropped because they were empty.
.It dropbuf
The number of buffers dropped because the number of buffers kept in the kernel
exceeds the limit.
.It dropbuf_samples
The number of samples dropped because the buffers containing the samples
were dropped.
.El
.\" ------------------------------------------------------------
.\".Sh HISTORY
.\"The
.\".Nm
.\"utility first appeared in
.\".Nx XXX .
.\" ------------------------------------------------------------
.Sh SEE ALSO
.Xr tpfmt 1 ,
.Xr tprof 4
.\" ------------------------------------------------------------
.Sh AUTHORS
The
.Nm
utility is written by
.An YAMAMOTO Takashi .
.\" ------------------------------------------------------------
.Sh CAVEATS
The contents and representation of recorded samples are undocumented and
will likely be changed for future releases of
.Nx
in an incompatible way.