'\" te
.\"  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH tnfxtract 1 "19 Aug 2003" "SunOS 5.11" "User Commands"
.SH NAME
tnfxtract \- extract kernel probes output into a trace file
.SH SYNOPSIS
.LP
.nf
\fBtnfxtract\fR [\fB-d\fR \fIdumpfile\fR \fB-n\fR \fInamelist\fR] \fItnf_file\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBtnfxtract\fR utility collects kernel trace output from an in-core buffer
in the Solaris kernel, or from the memory image of a crashed system, and
generates a binary \fBTNF\fR trace file like those produced directly by user
programs being traced.
.sp
.LP
Either both or neither of the \fB-d\fR and \fB-n\fR options must be specified.
If neither is specified, trace output is extracted from the running kernel. If
both are specified, the \fB-d\fR argument names the file containing the
(crashed) system memory image, and the \fB-n\fR argument names the file
containing the symbol table for the system memory image.
.sp
.LP
The \fBTNF\fR trace file \fItnf_file\fR produced is exactly the same size as
the in-core buffer; it is essentially a snapshot of that buffer.  It is legal
to run \fBtnfxtract\fR while kernel tracing is active, i.e., while the in-core
buffer is being written. \fBtnfxtract\fR insures that the output file it
generates is low-level consistent, that is, that only whole probes are written
out, and that internal data structures in the buffer are not corrupted because
the buffer is being concurrently written.
.sp
.LP
The \fBTNF\fR trace file generated is suitable as input to \fBtnfdump\fR(1),
which will generate an \fBASCII\fR file.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-d\fR \fIdumpfile\fR\fR
.ad
.RS 15n
.rt  
Uses \fIdumpfile\fR as the system memory image, instead of the running kernel.
The \fIdumpfile\fR is normally the path name of a file generated by the
\fBsavecore\fR utility.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-n\fR \fInamelist\fR\fR
.ad
.RS 15n
.rt  
Uses \fInamelist\fR as the file containing the symbol table information for the
given \fIdumpfile\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.mk
.na
\fB\fItnf_file\fR\fR
.ad
.RS 12n
.rt  
Output file generated by \fBtnfxtract\fR based on kernel trace output from an
in-core buffer in the Solaris kernel.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRExtracting probes from a running kernel
.sp
.LP
Extract probes from the running kernel into \fBktrace.out\fR:

.sp
.in +2
.nf
example% \fBtnfxtract ktrace.out\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRExtracting probes from a kernel crash dump
.sp
.LP
Extract probes from a kernel crash dump into \fBktrace.out\fR:

.sp
.in +2
.nf
example% \fBtnfxtract -d /var/crash/`uname -n`/vmcore.0 \e
   -n /var/crash/`uname -n`/unix.0 ktrace.out\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 6n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
.rt  
An error occurred.
.RE

.SH SEE ALSO
.sp
.LP
\fBprex\fR(1), \fBtnfdump\fR(1), \fBsavecore\fR(1M),
\fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)