=head1 SYNOPSIS
-B<fstrace dump> [B<-set> <I<set_name>>+] [-follow <I<log_name>>]
-[B<-file> <I<output_filename>>]
- [B<-sleep> <I<seconds_between_reads>>] [-help]
+B<fstrace dump> [B<-set> <I<set name>>+] [B<-follow> <I<log name>>]
+ [B<-file> <I<output filename>>] [B<-sleep> <I<seconds between reads>>]
+ [B<-help>]
-B<fstrace d> [B<-se> <I<set_name>>+] [B<-fo> <I<log_name>>] [-fi <I<output_filename>>]
-[B<-sl> <I<seconds_between_reads>>] [B<-h>]
+B<fstrace d> [B<-se> <I<set name>>+] [B<-fo> <I<log name>>]
+ [B<-fi> <I<output filename>>] [B<-sl> <I<seconds between reads>>]
+ [B<-h>]
=head1 DESCRIPTION
-The fstrace dump command displays the current contents of the
-B<cmfx> trace log on the standard output stream or writes it to the
-file named by the B<-file> argument.
+The B<fstrace dump> command displays the current contents of the C<cmfx>
+trace log on the standard output stream or writes it to the file named by
+the B<-file> argument.
To write the log continuously to the standard output stream or to a file,
-use the B<-follow> 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> argument.
+use the B<-follow> 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> argument.
=head1 CAUTIONS
-This command produces output only if the cm event set is
-active. To display or set the event set's state, use the
-B<fstrace lsset> or B<fstrace setset> command
-respectively.
+This command produces output only if the C<cm> event set is active. To
+display or set the event set's state, use the B<fstrace lsset> or
+B<fstrace setset> command respectively.
To make the output from this command maximally readable, the message
-catalog file called B<afszcm.cat> must reside in the local
-B</usr/vice/etc/C> directory. If necessary, copy the file to
-that directory from the AFS Binary Distribution before activating
-tracing.
-
-When the cm event set is active, a defined amount of kernel
-memory (by default, 60 KB) is allocated for the B<cmfx> trace
-log. As described on the introductory B<fstrace> 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> command; to display
-the log buffer's current size, use the B<fstrace lslog> command
+catalog file called F<afszcm.cat> must reside in the local
+F</usr/vice/etc/C> directory. If necessary, copy the file to that
+directory from the AFS Binary Distribution before activating tracing.
+
+When the C<cm> event set is active, a defined amount of kernel memory (by
+default, 60 KB) is allocated for the C<cmfx> trace log. As described in
+L<fstrace(8)>, 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> command; to
+display the log buffer's current size, use the B<fstrace lslog> command
with the B<-long> argument.
=head1 OPTIONS
=over 4
-=item -set
+=item B<-set> <I<set name>>+
-Names the event set for which to write out the associated trace
-log. The only acceptable value is B<cm> (for which the
-associated trace log is B<cmfx>). Provide either this argument
-or the B<-log> argument, or omit both to write out the B<cmfx>
-log by default.
+Names the event set for which to write out the associated trace log. The
+only acceptable value is C<cm> (for which the associated trace log is
+C<cmfx>). Provide either this argument or the B<-log> argument, or omit
+both to write out the C<cmfx> log by default.
-=item -follow
+=item B<-follow> <I<log name>>
Names the trace log to write out continuously at a specified interval (by
-default, every ten seconds; use the B<-sleep> argument to change
-the interval). The log is cleared after each write operation.
+default, every ten seconds; use the B<-sleep> argument to change the
+interval). The log is cleared after each write operation.
-The only acceptable value is cmfx. Provide either this
-argument or the B<-set> argument, or omit both to write out the
-B<cmfx> log by default.
+The only acceptable value is C<cmfx>. Provide either this argument or the
+B<-set> argument, or omit both to write out the C<cmfx> log by default.
-=item -file
+=item B<-file> <I<output filename>>
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.
+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.
-=item -sleep
+=item B<-sleep> <I<seconds between reads>>
-Sets the number of seconds between writes of the trace log's contents
-when it is dumped continuously. Provide the B<-follow> argument
-along with this one. If this argument is omitted, the default interval
-is ten seconds.
+Sets the number of seconds between writes of the trace log's contents when
+it is dumped continuously. Provide the B<-follow> argument along with this
+one. If this argument is omitted, the default interval is ten seconds.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 OUTPUT
The output begins with a header specifying the date and time at which the
-write operation began. If the B<-follow> argument is not
-included, the header also reports the number of logs being dumped; it is
-always C<1>, since there is only the B<cmfx> trace log.
-The format of the header is as follows:
+write operation began. If the B<-follow> argument is not included, the
+header also reports the number of logs being dumped; it is always C<1>,
+since there is only the C<cmfx> trace log. The format of the header is as
+follows:
AFS Trace Dump -
Date: I<starting_timestamp>
Each subsequent message describes a Cache Manager operation in the
following format:
- time I<timestamp>, pid I<pid>:I<event_message>
+ time <timestamp>, pid <pid>:<event_message>
where
=over 4
-=item I<timestamp
->
+=item <timestamp>
Specifies the time at which the Cache Manager performed the operation, as
-the number of seconds since the dump began
+the number of seconds since the dump began.
-=item I<pid
->
+=item <pid>
Specifies the process ID of the process or thread associated with the
-message
+message.
-=item I<event_message
->
+=item <event_message>
-Is the message itself. They are generally meaningful only to
-someone familiar with the AFS source code.
+Is the message itself. They are generally meaningful only to someone
+familiar with the AFS source code.
=back
-In addition, every 1024 seconds the fstrace command interpreter
-writes a message that records the current clock time, in the following
-format:
+In addition, every 1024 seconds the fstrace command interpreter writes a
+message that records the current clock time, in the following format:
- time I<timestamp>, pid I<pid>: Current time: I<unix_time>
+ time <timestamp>, pid <pid>: Current time: <unix_time>
where
=over 4
-=item I<timestamp
->
+=item <timestamp>
-Is the number of seconds from the start of trace logging
+Is the number of seconds from the start of trace logging.
-=item I<pid
->
+=item <pid>
-Is the process ID number
+Is the process ID number.
-=item I<unix_time
->
+=item <unix_time>
-Is the machine's clock time, represent in the standard UNIX time
-format as the number of seconds since midnight on January 1, 1970.
+Is the machine's clock time, represent in the standard UNIX time format as
+the number of seconds since midnight on January 1, 1970.
=back
Use this message to determine the actual clock time associated with each
log message. Determine the actual time as follows:
+=over 4
+
=item *
Locate the message of interest.
-
=item *
Search backward through the trace file for the closest current time
message.
-
=item *
-If the current time message's I<timestamp> is smaller than the
-log message's I<timestamp>, subtract former from the latter.
-If the current time message's I<timestamp> is larger than the log
-message's I<timestamp>, add 1024 to the latter and subtract the
-former from the result.
-
+If the current time message's timestamp is smaller than the log message's
+timestamp, subtract former from the latter. If the current time message's
+timestamp is larger than the log message's timestamp, add 1024 to the
+latter and subtract the former from the result.
=item *
-Add the resulting number to the current time message's
-I<unix_time> to determine the log message's actual time.
-
+Add the resulting number to the current time message's <unix_time> to
+determine the log message's actual time.
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:
+tracing was activated, the following message appears at the appropriate
+place in the output:
Log wrapped; data missing.
-To reduce the likelihood of overwriting, use the fstrace setlog
-command to increase the kernel buffer's size. To display the
-current defined buffer size, use the B<fstrace lslog> command with the
-B<-long> argument.
+To reduce the likelihood of overwriting, use the B<fstrace setlog> command
+to increase the kernel buffer's size. To display the current defined
+buffer size, use the B<fstrace lslog> command with the B<-long> argument.
The following message at the end of the log dump indicates that it is
completed:
=head1 EXAMPLES
-The following command dumps the log associated with the cm event
-set to the standard output stream.
+The following command dumps the log associated with the cm event set to
+the standard output stream.
# fstrace dump -set cm
AFS Trace Dump -
time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
AFS Trace Dump - Completed
-The following command dumps the trace log associated with the cm
-event set on the local machine to the file
-B<cmfx.dump.file.1>, using the default interval
-of 10 seconds between successive dumps:
+The following command dumps the trace log associated with the cm event set
+on the local machine to the file C<cmfx.dump.file.1>, using the default
+interval of 10 seconds between successive dumps:
# fstrace dump -follow cmfx -file cmfx.dump.file.1
=head1 PRIVILEGE REQUIRED
-The issuer must be logged in as the local superuser root.
+The issuer must be logged in as the local superuser C<root>.
=head1 SEE ALSO
-L<afszcm.cat(1)>,
-L<fstrace(1)>,
-L<fstrace_lslog(1)>,
-L<fstrace_setlog(1)>,
-L<fstrace_lsset(1)>
+L<afszcm.cat(5)>,
+L<fstrace(8)>,
+L<fstrace_lslog(8)>,
+L<fstrace_setlog(8)>,
+L<fstrace_lsset(8)>
=head1 COPYRIGHT
git://git.openafs.org / openafs.git / blobdiff