1 files changed, 183 insertions, 0 deletions
diff --git a/usr.bin/kdump/kdump.1 b/usr.bin/kdump/kdump.1
new file mode 100644
index 0000000..c03985e
--- /dev/null
+++ b/usr.bin/kdump/kdump.1
@@ -0,0 +1,183 @@
+.\" Copyright (c) 1990, 1993
+.\"	The Regents of the University of California.  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.
+.\" 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.
+.\"
+.\"	@(#)kdump.1	8.1 (Berkeley) 6/6/93
+.\" $FreeBSD$
+.\"
+.Dd April 5, 2012
+.Dt KDUMP 1
+.Os
+.Sh NAME
+.Nm kdump
+.Nd display kernel trace data
+.Sh SYNOPSIS
+.Nm
+.Op Fl dEnlHRsTA
+.Op Fl f Ar trfile
+.Op Fl m Ar maxdata
+.Op Fl p Ar pid
+.Op Fl t Ar trstr
+.Sh DESCRIPTION
+The
+.Nm
+command displays the kernel trace files produced with
+.Xr ktrace 1
+in human readable format.
+By default, the file
+.Pa ktrace.out
+in the current directory is displayed.
+.Pp
+The options are as follows:
+.Bl -tag -width Fl
+.It Fl d
+Display all numbers in decimal.
+.It Fl E
+Display elapsed timestamps (time since beginning of trace).
+.It Fl f Ar trfile
+Display the specified file instead of
+.Pa ktrace.out .
+.It Fl H
+List the thread ID (tid) of the thread with each trace record, if available.
+If no thread ID is available, 0 will be printed.
+.It Fl l
+Loop reading the trace file, once the end-of-file is reached, waiting for
+more data.
+.It Fl m Ar maxdata
+Display at most
+.Ar maxdata
+bytes when decoding
+.Tn I/O .
+.It Fl n
+Suppress ad hoc translations.
+Normally
+.Nm
+tries to decode many system calls into a more human readable format.
+For example,
+.Xr ioctl 2
+values are replaced with the macro name and
+.Va errno
+values are replaced with the
+.Xr strerror 3
+string.
+Suppressing this feature yields a more consistent output format and is
+easily amenable to further processing.
+.It Fl p Ar pid
+Display only trace events that correspond to the process
+.Ar pid .
+This may be useful when there are multiple processes recorded in the
+same trace file.
+.It Fl R
+Display relative timestamps (time since previous entry).
+.It Fl r
+When decoding STRU records, display structure members such as UIDs,
+GIDs, dates etc. symbolically instead of numerically.
+.It Fl s
+Suppress display of I/O data.
+.It Fl T
+Display absolute timestamps for each entry (seconds since epoch).
+.It Fl A
+Display description of the ABI of traced process.
+.It Fl t Ar trstr
+See the
+.Fl t
+option of
+.Xr ktrace 1 .
+.El
+.Pp
+The output format of
+.Nm
+is line oriented with several fields.
+The example below shows a section of a kdump generated by the following
+commands:
+.Bd -literal -offset indent
+?> ktrace echo "ktrace"
+
+?> kdump
+
+ 85045 echo     CALL  writev(0x1,0x804b030,0x2)
+ 85045 echo     GIO   fd 1 wrote 7 bytes
+       "ktrace
+       "
+ 85045 echo     RET   writev 7
+.Ed
+.Pp
+The first field is the PID of the process being traced.
+The second field is the name of the program being traced.
+The third field is the operation that the kernel performed
+on behalf of the process.
+If thread IDs are being printed, then an additional thread ID column will be
+added to the output between the PID field and program name field.
+.Pp
+In the first line above, the kernel executes the
+.Xr writev 2
+system call on behalf of the process so this is a
+.Li CALL
+operation.
+The fourth field shows the system call that was executed,
+including its arguments.
+The
+.Xr writev 2
+system call takes a file descriptor, in this case 1, or standard
+output, then a pointer to the iovector to write, and the number of
+iovectors that are to be written.
+In the second line we see the operation was
+.Li GIO ,
+for general I/O, and that file descriptor 1 had
+seven bytes written to it.
+This is followed by the seven bytes that were written, the string
+.Qq Li ktrace
+with a carriage return and line feed.
+The last line is the
+.Li RET
+operation, showing a return from the kernel, what system call we are
+returning from, and the return value that the process received.
+Seven bytes were written by the
+.Xr writev 2
+system call, so 7 is the return value.
+.Pp
+The possible operations are:
+.Bl -column -offset indent ".Li CALL" ".No data from user process"
+.It Sy Name Ta Sy Operation Ta Sy Fourth field
+.It Li CALL Ta enter syscall Ta syscall name and arguments
+.It Li RET Ta return from syscall Ta syscall name and return value
+.It Li NAMI Ta file name lookup Ta path to file
+.It Li GIO Ta general I/O Ta fd, read/write, number of bytes
+.It Li PSIG Ta signal Ta signal name, handler, mask, code
+.It Li CSW Ta context switch Ta stop/resume user/kernel
+.It Li USER Ta data from user process Ta the data
+.It Li STRU Ta various syscalls Ta structure
+.It Li SCTL Ta Xr sysctl 3 requests Ta MIB name
+.It Li PFLT Ta enter page fault Ta fault address and type
+.It Li PRET Ta return from page fault Ta fault result
+.El
+.Sh SEE ALSO
+.Xr ktrace 1
+.Sh HISTORY
+The
+.Nm
+command appeared in
+.Bx 4.4 .