2
<title>The Message Logging System</title>
5
&app;'s common message logging system uses a <emphasis>printf()</emphasis>
6
style format. Despite the C-like appearance, however, &app;'s LogFile class
7
by default does not use <emphasis>printf()</emphasis> for formatting the
12
All logging calls are converted using templated functions to use boost::format.
13
This uses a similar syntax to printf(), but additionally guarantees type-safety
14
and allows more advanced substition using positional identifiers besides the
15
traditional printf() type identifiers. The conversion templates mean that
16
the logging API remains exactly the same, regardless of which method is
17
used to format the log output.
21
The templates for conversion are generated using Boost.Preprocessor. Currently,
22
they allow for a maximum of 16 arguments (more than enough for all current
23
usage), but that can be expanded or reduced by changing
24
<emphasis>#define ARG_NUMBER</emphasis> in <emphasis>libbase/log.h</emphasis>.
28
If a filename is not specified before the log file is needed, a
29
default name of <emphasis>gnash-dbg.log</emphasis> is used. If Gnash is
30
started from the command line, the debug log will be created in
31
the current directory. When executing Gnash from a launcher under
32
<emphasis>GNOME</emphasis> or <emphasis>KDE</emphasis> the debug file goes in your
33
home directory, since that's considered the current directory. A file name
34
can be specified using either <emphasis>gnashrc</emphasis> or a
35
call to the LogFile instance itself.
39
<title>Logging System API</title>
42
&app; provides 9 specialized logging calls, each using the <emphasis>printf()</emphasis>-style
44
<programlisting>log_error(const char* fmt, ...)</programlisting>
46
calls and their purposes are described below. The output to stdout and to disk
47
are always identical, although writing the log to disk can be separately disabled.
52
<term>log_error</term>
55
Display an error message if verbose output is enabled. This is
56
always printed at a verbosity level of 1 or more.
62
<term>log_unimpl</term>
65
Displays a warning to the user about missing Gnash features.
66
We expect all calls to this function to disappear over time, as we
67
implement those features of Flash. This is
68
always printed at a verbosity level of 1 or more.
74
<term>log_trace</term>
77
Used only for the output of the ActionScript <emphasis>trace()</emphasis>
79
always printed at a verbosity level of 1 or more.
84
<term>log_debug</term>
87
Logs debug information. This is printed at a verbosity level of 2 or more.
92
<term>log_action</term>
95
Log action execution information. Wrap all calls to this
96
function (and other related statements) into an
97
IF_VERBOSE_ACTION macro, so to allow completely removing
98
all the overhead at compile time and reduce it at
99
runtime. This is printed at a verbosity level of 1 or more
100
only if action logging is enabled.
105
<term>log_parse</term>
108
Log SWF parsing Wrap all calls to this function (and
109
other related statements) into an IF_VERBOSE_PARSE macro,
110
so to allow completely removing all the overhead at
111
compile time and reduce it at runtime. This is printed at a
112
verbosity level of 1 or more
113
only if parser logging is enabled.
118
<term>log_security</term>
121
Display a message with security related information. This is always
122
printed at a verbosity level of 1 or more.
127
<term>log_swferror</term>
130
This indicates an error in how the binary SWF file was
131
constructed, i.e.probably a bug in the tools used to build
132
the SWF file. Wrap all calls to this function (and other
133
related statements) into an IF_VERBOSE_MALFORMED_SWF
134
macro, so to allow completely removing all the overhead at
135
compile time and reduce it at runtime. This is printed at a
136
verbosity level of 1 or more
137
only if malformed SWF logging is enabled.
143
<term>void log_aserror</term>
146
This indicates an erroneous actionscript request such as
147
an incorrect number of arguments or an invalid argument.
148
Wrap all calls to this function (and other
149
related statements) into an IF_VERBOSE_ASCODING_ERRORS
150
macro, so to allow completely removing all the overhead at
151
compile time and reduce it at runtime.
153
verbosity level of 1 or more
154
only if AS coding error logging is enabled.
162
<sect3 id="logfileinstance">
163
<title>The LogFile Instance</title>
166
This is the main API for initializing and manipulating the logging output.
167
By default, the log will be written to <emphasis>gnash-dbg.log</emphasis>
168
file whenever a verbose option is
174
<term>getDefaultInstance()</term>
177
This allows the construction of a LogFile on the first call, so
178
ensuring that it the logfile is always initialised before use.
179
It is the only way to access a LogFile instance. The logfile
180
itself is never opened until it is needed.
185
<term>setLogFilename(const std::string& filename)</term>
188
Use this to set a different name for the disk-based log file.
189
This setting can be overridden by a directive in gnashrc. If the
190
log file is already open, a call to setLogFilename() will close it;
191
a file with the new name will be opened when it is next needed.
197
<term>closeLog()</term>
200
Close a debug log. The disk file remains.
205
<term>removeLog()</term>
208
Delete the debug log file from disk.
213
<term>setVerbosity()</term>
216
Increment the verbosity level.
221
<term>setVerbosity(int level)</term>
224
Set the verbosity level to a specified level.
229
<term>setStamp(bool flag)</term>
232
If <emphasis>flag</emphasis> is <emphasis>true</emphasis>, then print a
233
timestamp prefixed to every output line. If
234
<emphasis>flag</emphasis> is <emphasis>false</emphasis>, then don't print
240
<term>setWriteDisk(bool flag)</term>
243
If <emphasis>flag</emphasis> is <emphasis>true</emphasis>, then create the
244
disk file. If <emphasis>flag</emphasis> is <emphasis>false</emphasis>,
245
then don't create the disk file.
added
removed
doc/C/refmanual/logging.xml
