[src/trunk]: src/usr.sbin/tprof man page

[yamt <yamt%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/d6536e5e0824
branches:  trunk
changeset: 771608:d6536e5e0824
user:      yamt <yamt%NetBSD.org@localhost>
date:      Sat Nov 26 05:02:44 2011 +0000

description:
man page

diffstat:

 usr.sbin/tprof/Makefile |    4 +-
 usr.sbin/tprof/tprof.8  |  115 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+), 2 deletions(-)

diffs (132 lines):

diff -r 53a8123ef350 -r d6536e5e0824 usr.sbin/tprof/Makefile
--- a/usr.sbin/tprof/Makefile   Sat Nov 26 04:58:42 2011 +0000
+++ b/usr.sbin/tprof/Makefile   Sat Nov 26 05:02:44 2011 +0000
@@ -1,7 +1,7 @@
-#      $NetBSD: Makefile,v 1.2 2009/04/22 15:23:09 lukem Exp $
+#      $NetBSD: Makefile,v 1.3 2011/11/26 05:02:44 yamt Exp $
 
 PROG=  tprof
-NOMAN= 
+MAN=   tprof.8
 
 CPPFLAGS+= -I${NETBSDSRCDIR}/sys/
 
diff -r 53a8123ef350 -r d6536e5e0824 usr.sbin/tprof/tprof.8
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/usr.sbin/tprof/tprof.8    Sat Nov 26 05:02:44 2011 +0000
@@ -0,0 +1,115 @@
+.\"    $NetBSD: tprof.8,v 1.1 2011/11/26 05:02:44 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
+.Dt LS 1
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.Nm
+.Op Fl c
+.Op Fl o Ar file
+.Ar command ...
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+The
+.Nm
+is a simpling 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 its 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 "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 has 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 buffer contained the samples
+were dropped.
+.El
+.\" ------------------------------------------------------------
+.\.Sh HISTORY
+.\The
+.\.Nm
+.\utility first appeared in
+.\.Nx XXX .
+.\" ------------------------------------------------------------
+.Sh AUTHORS
+The
+.Nm
+utility is written by
+.An YAMAMOTO Takashi .
+.\" ------------------------------------------------------------
+.Sh SEE ALSO
+.Xr tpfmt 1 ,
+.Xr tprof 4