# The Message Logging System

&app;'s common message logging system uses a printf() style format. Despite the C-like appearance, however, &app;'s LogFile class by default does not use printf() for formatting the messages at all.

All logging calls are converted using templated functions to use boost::format. This uses a similar syntax to printf(), but additionally guarantees type-safety and allows more advanced substition using positional identifiers besides the traditional printf() type identifiers. The conversion templates mean that the logging API remains exactly the same, regardless of which method is used to format the log output.

The templates for conversion are generated using Boost.Preprocessor. Currently, they allow for a maximum of 16 arguments (more than enough for all current usage), but that can be expanded or reduced by changing #define ARG_NUMBER in libbase/log.h.

If a filename is not specified before the log file is needed, a default name of gnash-dbg.log is used. If Gnash is started from the command line, the debug log will be created in the current directory. When executing Gnash from a launcher under GNOME or KDE the debug file goes in your home directory, since that's considered the current directory. A file name can be specified using either gnashrc or a call to the LogFile instance itself.

## Logging System API

&app; provides 9 specialized logging calls, each using the printf()-style call similar to this:

    log_error(const char* fmt, ...)

The different calls and their purposes are described below. The output to stdout and to disk are always identical, although writing the log to disk can be separately disabled.

log_error

  Display an error message if verbose output is enabled. This is always printed at a verbosity level of 1 or more.

log_unimpl

  Displays a warning to the user about missing Gnash features. We expect all calls to this function to disappear over time, as we implement those features of Flash. This is always printed at a verbosity level of 1 or more.

log_trace

  Used only for the output of the ActionScript trace() function. This is always printed at a verbosity level of 1 or more.

log_debug

  Logs debug information. This is printed at a verbosity level of 2 or more.

log_action

  Log action execution information. Wrap all calls to this function (and other related statements) into an IF_VERBOSE_ACTION macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if action logging is enabled.

log_parse

  Log SWF parsing Wrap all calls to this function (and other related statements) into an IF_VERBOSE_PARSE macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if parser logging is enabled.

log_swferror

  This indicates an error in how the binary SWF file was constructed, i.e.probably a bug in the tools used to build the SWF file. Wrap all calls to this function (and other related statements) into an IF_VERBOSE_MALFORMED_SWF macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if malformed SWF logging is enabled.

log_aserror

  This indicates an erroneous actionscript request such as an incorrect number of arguments or an invalid argument. Wrap all calls to this function (and other related statements) into an IF_VERBOSE_ASCODING_ERRORS macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if AS coding error logging is enabled.

log_abc

  Extremely verbose logging related to AVM2/ABC execution. This is printed at verbosity level 3.

## The LogFile Instance

This is the main API for initializing and manipulating the logging output. By default, the log will be written to gnash-dbg.log file whenever a verbose option is supplied.

getDefaultInstance()

  This allows the construction of a LogFile on the first call, so ensuring that it the logfile is always initialised before use. It is the only way to access a LogFile instance. The logfile itself is never opened until it is needed.

setLogFilename(const std::string& filename)

  Use this to set a different name for the disk-based log file. This setting can be overridden by a directive in gnashrc. If the log file is already open, a call to setLogFilename() will close it; a file with the new name will be opened when it is next needed.

closeLog()

  Close a debug log. The disk file remains.

removeLog()

  Delete the debug log file from disk.

setVerbosity()

  Increment the verbosity level.

setVerbosity(int level)

  Set the verbosity level to a specified level.

setStamp(bool flag)

  If flag is true, then print a timestamp prefixed to every output line. If flag is false, then don't print a timestamp.

setWriteDisk(bool flag)

  If flag is true, then create the disk file. If flag is false, then don't create the disk file.