Update kdump manual page with information on the dump format.

Add a table with the different types of operations traced.

Reviewed by:	Ruslan Ermilov
Approved by:	Robert Watson (mentor)

1 files changed, 62 insertions, 1 deletions

diff --git a/usr.bin/kdump/kdump.1 b/usr.bin/kdump/kdump.1
index 76ad1c3..802f7cc 100644
--- a/usr.bin/kdump/kdump.1
+++ b/usr.bin/kdump/kdump.1
@@ -32,7 +32,7 @@
 .\"	@(#)kdump.1	8.1 (Berkeley) 6/6/93
 .\" $FreeBSD$
 .\"
-.Dd December 8, 2003
+.Dd January 28, 2005
 .Dt KDUMP 1
 .Os
 .Sh NAME
@@ -101,6 +101,67 @@ See the
 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.
+.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 GENIO" ".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 GENIO Ta general I/O Ta fd, read/write, number of bytes
+.It Li SIG 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
+.El
 .Sh SEE ALSO
 .Xr ktrace 1
 .Sh HISTORY