Update fstrace suite manpages
[openafs.git] / doc / man-pages / pod8 / fstrace_lslog.pod
1 =head1 NAME
2
3 fstrace_lslog - Displays information about a log
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fstrace lslog> S<<< [B<-set> <I<set name>>+] >>>
11     S<<< [B<-log> <I<log name>>] >>>
12     [B<-long>] [B<-help>]
13
14 B<fstrace lsl> S<<< [B<-s> <I<set name>>+] >>>
15     S<<< [B<-log> <I<log name>>] >>>
16     [B<-lon>] [B<-h>]
17
18 =for html
19 </div>
20
21 =head1 DESCRIPTION
22
23 The B<fstrace lslog> command reports whether the C<cmfx> log is available
24 for use. If the B<-long> argument is included, the output reports the
25 log's defined size, and whether that amount of space is currently
26 allocated in kernel memory or not.
27
28 To change the C<cmfx> trace log's size, use the B<fstrace setlog>
29 command. To display or set whether space is allocated for it in kernel
30 memory, use the B<fstrace lsset> or B<fstrace setset> command to display
31 or set the state of the corresponding C<cm> event set, respectively.
32
33 =head1 OPTIONS
34
35 =over 4
36
37 =item B<-set> <I<set name>>+
38
39 Names the event set for which to display information about the
40 corresponding trace log. The only acceptable value is C<cm> (for which the
41 associated trace log is C<cmfx>). Provide either this argument or the
42 B<-log> argument, or omit both to display information about the C<cmfx>
43 log by default.
44
45 =item B<-log> <I<log name>>
46
47 Names the trace log about which to report. The only acceptable value is
48 C<cmfx>. Provide either this argument or the B<-set> argument, or omit
49 both to report on the C<cmfx> log by default.
50
51 =item B<-long>
52
53 Reports the defined size of the log in kilobyte units and whether that
54 amount of space is currently allocated in kernel memory.
55
56 =item B<-help>
57
58 Prints the online help for this command. All other valid options are
59 ignored.
60
61 =back
62
63 =head1 OUTPUT
64
65 By default, the B<fstrace lslog> command displays only the name of the
66 available log, C<cmfx>, in the following format:
67
68    Available logs:
69    cmfx
70
71 When the B<-long> flag is included, the output also reports the defined
72 size of the log in kilobytes, and whether or not that amount of space is
73 currently allocated in kernel memory, in the following format:
74
75    Available logs:
76    cmfx : <log_size> kbytes (allocated | unallocated)
77
78 The C<allocated> state indicates that the indicated number of kilobytes is
79 reserved for the C<cmfx> trace log in kernel memory. The C<cm> event set's
80 state is either C<active> or C<inactive>, as reported by the B<fstrace
81 lsset> command, and set by the B<fstrace setset> command's B<-active> or
82 B<-inactive> flags respectively.
83
84 The C<unallocated> state indicates that no kernel memory is currently
85 reserved for the C<cmfx> trace log. The B<cm> event set's state is
86 C<dormant>, as reported by the B<fstrace lsset> command and set by the
87 B<fstrace setset> command's B<-dormant> flag. If the event set's state is
88 later changed to active or inactive, the number of kilobytes indicated as
89 <log_size> are again allocated in kernel memory.
90
91 =head1 EXAMPLES
92
93 The following example uses the -long flag to display information
94 about the C<cmfx> log:
95
96    # fstrace lslog -log cmfx -long
97    Available logs:
98    cmfx : 60 kbytes (allocated)
99
100 =head1 PRIVILEGE REQUIRED
101
102 The issuer must be logged in as the local superuser C<root>.
103
104 =head1 SEE ALSO
105
106 L<fstrace(8)>,
107 L<fstrace_lsset(8)>,
108 L<fstrace_setlog(8)>
109
110 =head1 COPYRIGHT
111
112 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
113
114 This documentation is covered by the IBM Public License Version 1.0.  It was
115 converted from HTML to POD by software written by Chas Williams and Russ
116 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.