--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
+<HTML><HEAD>
+<TITLE>Administration Reference</TITLE>
+<!-- Begin Header Records ========================================== -->
+<!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID -->
+<!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30 -->
+<META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
+<META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
+<META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
+</HEAD><BODY>
+<!-- (C) IBM Corporation 2000. All Rights Reserved -->
+<BODY bgcolor="ffffff">
+<!-- End Header Records ============================================ -->
+<A NAME="Top_Of_Page"></A>
+<H1>Administration Reference</H1>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf171.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf173.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<P>
+<H2><A NAME="HDRFSTRACE_DUMP" HREF="auarf002.htm#ToC_186">fstrace dump</A></H2>
+<P><STRONG>Purpose</STRONG>
+<A NAME="IDX5031"></A>
+<A NAME="IDX5032"></A>
+<P>Dumps a trace log
+<P><STRONG>Synopsis</STRONG>
+<PRE><B>fstrace dump</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-follow</B> <<VAR>log_name</VAR>>]
+ [<B>-file</B> <<VAR>output_filename</VAR>>]
+ [<B>-sleep</B> <<VAR>seconds_between_reads</VAR>>] [<B>-help</B>]
+
+<B>fstrace d</B> [<B>-se</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-fo</B> <<VAR>log_name</VAR>>] [<B>-fi</B> <<VAR>output_filename</VAR>>]
+ [<B>-sl</B> <<VAR>seconds_between_reads</VAR>>] [<B>-h</B>]
+</PRE>
+<P><STRONG>Description</STRONG>
+<P>The <B>fstrace dump</B> command displays the current contents of the
+<B>cmfx</B> trace log on the standard output stream or writes it to the
+file named by the <B>-file</B> argument.
+<P>To write the log continuously to the standard output stream or to a file,
+use the <B>-follow</B> argument. By default, the log's
+contents are written out every ten seconds and then automatically
+cleared. To change the interval between writes, use the
+<B>-sleep</B> argument.
+<P><STRONG>Cautions</STRONG>
+<P>This command produces output only if the <B>cm</B> event set is
+active. To display or set the event set's state, use the
+<B>fstrace lsset</B> or <B>fstrace setset</B> command
+respectively.
+<P>To make the output from this command maximally readable, the message
+catalog file called <B>afszcm.cat</B> must reside in the local
+<B>/usr/vice/etc/C</B> directory. If necessary, copy the file to
+that directory from the AFS Binary Distribution before activating
+tracing.
+<P>When the <B>cm</B> event set is active, a defined amount of kernel
+memory (by default, 60 KB) is allocated for the <B>cmfx</B> trace
+log. As described on the introductory <B>fstrace</B> reference
+page, when the buffer is full, messages are overwritten in a circular fashion
+(new messages overwrite the oldest ones). To allocate more kernel
+memory for the log, use the <B>fstrace setlog</B> command; to display
+the log buffer's current size, use the <B>fstrace lslog</B> command
+with the <B>-long</B> argument.
+<P><STRONG>Options</STRONG>
+<DL>
+<P><DT><B>-set
+</B><DD>Names the event set for which to write out the associated trace
+log. The only acceptable value is <B>cm</B> (for which the
+associated trace log is <B>cmfx</B>). Provide either this argument
+or the <B>-log</B> argument, or omit both to write out the <B>cmfx</B>
+log by default.
+<P><DT><B>-follow
+</B><DD>Names the trace log to write out continuously at a specified interval (by
+default, every ten seconds; use the <B>-sleep</B> argument to change
+the interval). The log is cleared after each write operation.
+<P>The only acceptable value is <B>cmfx</B>. Provide either this
+argument or the <B>-set</B> argument, or omit both to write out the
+<B>cmfx</B> log by default.
+<P><DT><B>-file
+</B><DD>Specifies the pathname of the file to which to write the trace log's
+contents. It can be in AFS or on the local disk. Partial
+pathnames are interpreted relative to the current working directory. If
+this argument is omitted, the trace log appears on the standard output
+stream.
+<P><DT><B>-sleep
+</B><DD>Sets the number of seconds between writes of the trace log's contents
+when it is dumped continuously. Provide the <B>-follow</B> argument
+along with this one. If this argument is omitted, the default interval
+is ten seconds.
+<P><DT><B>-help
+</B><DD>Prints the online help for this command. All other valid options
+are ignored.
+</DL>
+<P><STRONG>Output</STRONG>
+<P>The output begins with a header specifying the date and time at which the
+write operation began. If the <B>-follow</B> argument is not
+included, the header also reports the number of logs being dumped; it is
+always <TT>1</TT>, since there is only the <B>cmfx</B> trace log.
+The format of the header is as follows:
+<PRE> AFS Trace Dump -
+ Date: <VAR>starting_timestamp</VAR>
+ Found 1 logs.
+ Contents of log cmfx:
+
+</PRE>
+<P>Each subsequent message describes a Cache Manager operation in the
+following format:
+<PRE> time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>:<VAR>event_message</VAR>
+
+</PRE>
+<P>where
+<DL>
+<P><DT><B><VAR>timestamp</VAR>
+</B><DD>Specifies the time at which the Cache Manager performed the operation, as
+the number of seconds since the dump began
+<P><DT><B><VAR>pid</VAR>
+</B><DD>Specifies the process ID of the process or thread associated with the
+message
+<P><DT><B><VAR>event_message</VAR>
+</B><DD>Is the message itself. They are generally meaningful only to
+someone familiar with the AFS source code.
+</DL>
+<P>In addition, every 1024 seconds the <B>fstrace</B> command interpreter
+writes a message that records the current clock time, in the following
+format:
+<PRE> time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>: Current time: <VAR>unix_time</VAR>
+
+</PRE>
+<P>where
+<DL>
+<P><DT><B><VAR>timestamp</VAR>
+</B><DD>Is the number of seconds from the start of trace logging
+<P><DT><B><VAR>pid</VAR>
+</B><DD>Is the process ID number
+<P><DT><B><VAR>unix_time</VAR>
+</B><DD>Is the machine's clock time, represent in the standard UNIX time
+format as the number of seconds since midnight on January 1, 1970.
+</DL>
+<P>Use this message to determine the actual clock time associated with each
+log message. Determine the actual time as follows:
+<OL TYPE=1>
+<P><LI>Locate the message of interest.
+<P><LI>Search backward through the trace file for the closest current time
+message.
+<P><LI>If the current time message's <VAR>timestamp</VAR> is smaller than the
+log message's <VAR>timestamp</VAR>, subtract former from the latter.
+If the current time message's <VAR>timestamp</VAR> is larger than the log
+message's <VAR>timestamp</VAR>, add 1024 to the latter and subtract the
+former from the result.
+<P><LI>Add the resulting number to the current time message's
+<VAR>unix_time</VAR> to determine the log message's actual time.
+</OL>
+<P>If any of the data in the kernel trace buffer has been overwritten since
+tracing was activated, the following message appears at the appropriate place
+in the output:
+<PRE> Log wrapped; data missing.
+
+</PRE>
+<P>To reduce the likelihood of overwriting, use the <B>fstrace setlog</B>
+command to increase the kernel buffer's size. To display the
+current defined buffer size, use the <B>fstrace lslog</B> command with the
+<B>-long</B> argument.
+<P>The following message at the end of the log dump indicates that it is
+completed:
+<PRE> AFS Trace Dump - Completed
+
+</PRE>
+<P><STRONG>Examples</STRONG>
+<P>The following command dumps the log associated with the <B>cm</B> event
+set to the standard output stream.
+<PRE> # <B>fstrace dump -set cm</B>
+ AFS Trace Dump -
+ Date: Tue Apr 7 10:54:57 1998
+ Found 1 logs.
+ time 32.965783, pid 0: Tue Apr 7 10:45:52 1998
+ time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
+ time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0)
+ time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
+ time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
+ .
+ .
+ .
+ time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
+ fid (756 4fb7e:588d240.2ff978a8.6)
+ time 71.440569, pid 33658: Returning code 2 from 19
+ time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2)
+ time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
+ AFS Trace Dump - Completed
+
+</PRE>
+<P>The following command dumps the trace log associated with the <B>cm</B>
+event set on the local machine to the file
+<B>cmfx.dump.file.1</B>, using the default interval
+of 10 seconds between successive dumps:
+<PRE> # <B>fstrace dump -follow cmfx -file cmfx.dump.file.1</B>
+
+</PRE>
+<P><STRONG>Privilege Required</STRONG>
+<P>The issuer must be logged in as the local superuser <B>root</B>.
+<P><STRONG>Related Information</STRONG>
+<P><A HREF="auarf041.htm#HDRAFSZCM">afszcm.cat</A>
+<P><A HREF="auarf169.htm#HDRFSTRACE_INTRO">fstrace</A>
+<P><A HREF="auarf174.htm#HDRFSTRACE_LSLOG">fstrace lslog</A>
+<P><A HREF="auarf176.htm#HDRFSTRACE_SETLOG">fstrace setlog</A>
+<P><A HREF="auarf175.htm#HDRFSTRACE_LSSET">fstrace lsset</A>
+<P>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf171.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf173.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<!-- Begin Footer Records ========================================== -->
+<P><HR><B>
+<br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
+</B>
+<!-- End Footer Records ============================================ -->
+<A NAME="Bot_Of_Page"></A>
+</BODY></HTML>