# The Debug Logging System

Gnash supports a debug logging system that supports both C and C++ natively. This means you can use both `printf()` style debug messages and C++ `iostreams` style, where you can print C++ objects directly as you would when using `cout`.

In the beginning, Gnash only supported the C API for debug logging, so that is the most heavily used in Gnash. This API was the `log_msg()` and `log_error()` functions, and used a callback to set them up.

It became apparent one day the callback was never needed, and I got tired of having to use `c_str()` on string data just to print them out.

If a filename is not specified at object construction time, a default name of `gnash-dbg.log` is used. If Gnash was 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.

There is common functionality between using the C or C++ API. Optional output is based on flags that can be set or unset. Multiple levels of verbosity are supported, so you can get more output by supplying multiple `-v` options on the command line. You can also disable the creating of the debug log.

## Logging System C API

These functions are clones of the originals as they were used for Gnash. These function the same as always except outout can be logged to disk now as well. These currently print no timestamp with the output, which is the older functionality. As these functions are implemented on top of the C++ API now, they can be used without corrupting the output buffers.

void log_msg(const char* fmt, ...)

  Display a message if verbose output is enabled. By default the messages are always written to the disk file, but optionally displayed in the terminal.

log_error(const char* fmt, ...)

  Display an error message if verbose output is enabled. By default the error messages are always written to the disk file, but optionally displayed in the terminal.

log_warning(const char* fmt, ...)

  Display a warning message if verbose output is enabled. By default the error messages are always written to the disk file, but optionally displayed in the terminal.

## Logging System C++ API

This is the new C++ streams based API that can be used to print C++ objects natively. All output lines are timestamped.

There are two macros used for program tracing. these can be used in both C or C++ code with one little difference. Since C doesn't have destructors, you must call `GNASH_REPORT_RETURN` at the end of a function to display the function returning message.

GNASH_REPORT_FUNCTION;

  When this is included in a C++ method, a message is printed when entering and exiting this method by hooking into the constructor and destructor. These are always written to the disk file, but optionally written to the screen only at the highest levels of verbosity.

GNASH_REPORT_RETURN;

  This is used by C functions to print the returning from function debug message. For C++, this macro is executed automatically by the destructor.

This is the main API for the logging system. By default everything is setup to write to the default `gnash-dbg.log` file whenever a verbose option is supplied. Optionally it is possible to open a log file with a specified name, allowing multiple output files.

openLog(const char *filespec)

  Open the debug file with the name specified by `filespec`. This file goes in the current directory, or your home directory if using a menu based launcher.

closeLog(void)

  Close a debug log. The disk file remains.

removeLog(void)

  Delete the debug log file from disk.

setVerbosity(void)

  Increment the verbosity level.

setVerbosity(int)

  Set the verbosity 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.