aboutsummaryrefslogtreecommitdiffstats
path: root/lib/sasl/doc/src/rb.xml
blob: fa85b4bcd986f2454e03ab3294363e5e65ae1039 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.

    </legalnotice>

    <title>rb</title>
    <prepared>Martin Bj&ouml;rklund</prepared>
    <responsible>Martin Bj&ouml;rklund</responsible>
    <docno></docno>
    <approved>Bjarne D&auml;cker</approved>
    <checked></checked>
    <date>1996-10-16</date>
    <rev>A</rev>
    <file>rb.sgml</file>
  </header>
  <module>rb</module>
  <modulesummary>The Report Browser Tool</modulesummary>
  <description>
    <p>The Report Browser (RB) tool makes it possible to browse and
      format error reports written by the error logger handler
      <c>log_mf_h</c>.
      </p>
  </description>
  <funcs>
    <func>
      <name>filter(Filters)</name>
      <name>filter(Filters, Dates)</name>
      <fsummary>Filter reports and displays them on the screen</fsummary>
      <type>
        <v>Filters = [filter()]</v>
        <v>filter() = {Key, Value} | {Key, Value, no} | {Key, RegExp, re} | {Key, RegExp, re, no}</v>
        <v>Key = term()</v>
        <v>Value = term()</v>
        <v>RegExp = string() | {string, Options} | mp(), {mp(), Options}</v>
        <v>Dates = {DateFrom, DateTo} | {DateFrom, from} | {DateTo, to}</v>
        <v>DateFrom = DateTo = {date(), time()}</v>
        <v>date() and time() are the same type as in the <c>calendar</c> module</v>
      </type>
      <desc>
        <p>This function displays the reports that match the provided filters.</p>
        <p>
          When a filter includes the <c>no</c> atom it will exclude the reports that match
          that filter.
        </p>
        <p>
          The reports are matched using the <c>proplists</c> module. The report must be a proplist
          to be matched against any of the <c>filters()</c>.
        </p>
	<p>
	  If the filter is of the form <c>{Key, RegExp, re}</c> the report must contain an element with
	  <c>key = Key</c> and <c>Value</c> must match the RegExp regular expression.
	</p>
	<p>
	  If the Dates parameter is provided, then the reports are filtered according to the date
	  when they occurred. If Dates is of the form <c>{DateFrom, from}</c> then reports that occurred
	  after DateFrom are displayed.
	</p>
	<p>
	  If Dates is of the form <c>{DateTo, to}</c> then reports that occurred before DateTo
	  are displayed.
	</p>
	<p>
	  If two Dates are provided, then reports that occurred between those dates are returned.
	</p>
	<p>
	   If you only want to filter only by dates, then you can provide the empty list as the Filters
	   parameter.
	</p>
	<p>
	  See <c>rb:grep/1</c> for more information on the RegExp parameter.
	</p>
      </desc>
    </func>
    <func>
      <name>grep(RegExp)</name>
      <fsummary>Search the reports for a regular expression</fsummary>
      <type>
        <v>RegExp = string() | {string, Options} | mp(), {mp(), Options}</v>
      </type>
      <desc>
        <p>All reports containing the regular expression <c>RegExp</c>
          are printed.
          </p>
        <p><c>RegExp</c> can be a string containing the regular
          expression; a tuple with the string and the options for
	  compilation; a compiled regular expression; a compiled
	  regular expression and the options for running it.
	  Refer to the module <c>re</c> and specially the function <c>re:run/3</c>
	  for a definition of valid regular expressions and options.
          </p>
      </desc>
    </func>
    <func>
      <name>h()</name>
      <name>help()</name>
      <fsummary>Print help information</fsummary>
      <desc>
        <p>Prints the on-line help information.
          </p>
      </desc>
    </func>
    <func>
      <name>list()</name>
      <name>list(Type)</name>
      <fsummary>List all reports</fsummary>
      <type>
        <v>Type = type()</v>
        <v>type() = error | error_report | info_msg | info_report |
        warning_msg | warning_report | crash_report |
        supervisor_report | progress</v>
      </type>
      <desc>
        <p>This function lists all reports loaded in the
          <c>rb_server</c>. Each report is given a unique number that
          can be used as a reference to the report in the
          <c>show/1</c> function.
          </p>
        <p>If no <c>Type</c> is given, all reports are listed.
          </p>
      </desc>
    </func>
    <func>
      <name>log_list()</name>
      <name>log_list(Type)</name>
      <fsummary>Log reports list</fsummary>
      <type>
        <v>Type = type()</v>
        <v>type() = error | error_report | info_msg | info_report |
        warning_msg | warning_report | crash_report |
        supervisor_report | progress</v>
      </type>
      <desc>
	<p>Same as <c>list/0</c> or <c>list/1</c> functions 
	   but result is printed to logfile, if set, otherwise to standard_io.
          </p>
        <p>If no <c>Type</c> is given, all reports are listed.
          </p>
      </desc>
    </func>
    <func>
      <name>rescan()</name>
      <name>rescan(Options)</name>
      <fsummary>Rescan the report directory</fsummary>
      <type>
        <v>Options = [opt()]</v>
      </type>
      <desc>
        <p>Rescans the report directory. <c>Options</c> is the same as
          for <c>start()</c>.
          </p>
      </desc>
    </func>
    <func>
      <name>show()</name>
      <name>show(Report)</name>
      <fsummary>Show reports</fsummary>
      <type>
        <v>Report = int() | type()</v>
      </type>
      <desc>
        <p>If a type argument is given, all loaded reports of this
          type are printed. If an integer argument is given, the
          report with this reference number is printed. If no argument
          is given, all reports are shown.
          </p>
      </desc>
    </func>
    <func>
      <name>start()</name>
      <name>start(Options)</name>
      <fsummary>Start the RB server</fsummary>
      <type>
        <v>Options = [opt()]</v>
        <v>opt() = {start_log, FileName} | {max, MaxNoOfReports} | {report_dir, DirString} | {type, ReportType} | {abort_on_error, Bool}</v>
        <v>FileName = string() | atom() | pid()</v>
        <v>MaxNoOfReports = int() | all</v>
        <v>DirString = string()</v>
        <v>ReportType = type() | [type()] | all</v>
        <v>Bool = true | false</v>
      </type>
      <desc>
        <p>The function <c>start/1</c> starts the <c>rb_server</c>
          with the specified options, while <c>start/0</c> starts with
          default options. The <c>rb_server</c> must be started before
          reports can be browsed. When the <c>rb_server</c> is
          started, the files in the specified directory are
          scanned. The other functions assume that the server has
	  started.
          </p>
	  <p><c>{start_log, FileName}</c> starts logging to file, 
	  registered name or io_device. All reports will be printed 
	  to the named file. The default is <c>standard_io</c>. 
	  The option {start_log, standard_error} is not allowed and 
	  will be replaced by default standard_io.
          </p>
        <p><c>{max, MaxNoOfReports}</c>. Controls how many reports the
          <c>rb_server</c> should read on start-up. This option is
          useful as the directory may contain 20.000 reports. If this
          option is given, the <c>MaxNoOfReports</c> latest reports
          will be read. The default is 'all'.
          </p>
        <p><c>{report_dir, DirString}</c>. Defines the directory where
          the error log files are located. The default is <c>{sasl, error_logger_mf_dir}</c>.  </p>
        <p><c>{type, ReportType}</c>. Controls what kind of reports the
          <c>rb_server</c> should read on start-up.  <c>ReportType</c>
          is a supported type, 'all', or a list of supported
          types. The default is 'all'.
          </p>
        <p><c>{abort_on_error, Bool}</c>. This option specifies whether
          or not logging should be aborted if rb encounters an unprintable 
          report. (You may get a report on incorrect form if the 
          <c>error_logger</c> function <c>error_msg</c> or 
          <c>info_msg</c> has been called with an invalid format string).
          If <c>Bool</c> is <c>true</c>, rb will stop logging (and print an
          error message to stdout) if it encounters a badly formatted report.
          If logging to file is enabled, an error message will be appended to
          the log file as well. 
          If <c>Bool</c> is <c>false</c> (which is the default value), rb will 
          print an error message to stdout for every bad report it 
          encounters, but the logging process is never aborted. All printable 
          reports will be written. If logging to file is enabled, rb prints 
          <c>* UNPRINTABLE REPORT *</c> in the log file at the location of an 
          unprintable report.
          </p>
      </desc>
    </func>
    <func>
      <name>start_log(FileName)</name>
      <fsummary>Redirect all output to <c>FileName</c></fsummary>
      <type>
        <v>FileName = string() | atom() | pid()</v>
      </type>
      <desc>
        <p>Redirects all report output from the RB tool to the
          specified file, registered name or io_device.
          </p>
      </desc>
    </func>
    <func>
      <name>stop()</name>
      <fsummary>Stop the RB server</fsummary>
      <desc>
        <p>Stops the <c>rb_server</c>.
          </p>
      </desc>
    </func>
    <func>
      <name>stop_log()</name>
      <fsummary>Stop logging to file</fsummary>
      <desc>
        <p>Closes the log file. The output from the RB tool will be
          directed to <c>standard_io</c>.
          </p>
      </desc>
    </func>
  </funcs>
</erlref>