********************************************************************
* Note: We will change geas to use the debugging features of glib. *
* Use of the functions described here is depreciated.              *
********************************************************************

Console Output
==============

This document describes text output to the console from GEAS, and the
various compile time and run time options that affect what text is displated.

It is partly a developer guide, and partly a guide to the available options.


Compile time options:
---------------------

These arguments are passed to 'autogen.sh' (or 'configure') to select various
options

--with-debug          : Causes 'DEBUG' to be defined.
--with-security-debug : Causes 'SECURITY_DEBUG' and 'DEBUG' to be defined.
--enable-self-test    : Enable self test code


Run time options:
-----------------

    -d <level>    Sets debug level (low = 1, high = 10, or off)
    -u            Display usage (and quit)
    -v            Verbose mode
    -q            Quiet mode
    -C            Display configuration
    -l            Show class definitions


Verbose mode:
	Debugging output to stdere on (if DEBUG is defined)
	Status messages to stdout on
	Error/warning messages to stderr on

Quiet mode:
	Debugging output to stdere on (if DEBUG is defined)
	Status messages to stdout off
	Error/warning messages to stderr off

Default:
	Debugging output to stdere on (if DEBUG is defined)
	Status messages to stdout off
	Error/warning messages to stderr on

DEBUG mode turns 'verbose' on automatically.


Output functions:
-----------------

message( char *format , ... )
	This acts exactly like printf(), but will only display the string if
'verbose' is set to TRUE, and 'quiet' is set to FALSE. This should be used
for general server status messages that are not associated with a
particular operation.

	All output is to 'stdout'.


debug_output_f() [Usually called via a macro - see below.]
	This will only display text if DEBUG is defined, and debuglevel has
been set to a value, either by a command line option or in the
configuration file that is equal to or below the input level. It displays the
file, line, and function where it was called, and a string with printf()
formatting. A requested level of 'DEBUGLEVEL_ALWAYS' will always be printed,
provided 'DEBUG' is defined.

	Effectively, the 'debuglevel' setting filters debugging output. If
the function is called with an argument of 'DEBUGLEVEL_MEDIUM' then a
debuglevel setting lower than that will cause the message to be ignored,
but a setting greater than or equal to DEBUGLEVEL_MEDIUM will allow it to
be printed. Raising the debuglevel will therefore allow more debugging
detail to be printed.

	All output is to 'stderr'.


error_message_out() [Usually called via a macro - see below.]
	This is similar to debug_output_f(), but displays the file, line, and
function only if DEBUG is defined. The debuglevel setting does not affect
this function.

	All output is to 'stderr'.


Output macros:
--------------
self_test_message( char *format , ... )
	This macro acts like message(), but only displays text if SELF_TEST is
defined.


errormsg( char *format , ... )
	Calls error_message_out(), prepending "Error:" to the string.

	All server errors, rather than errors relating to an operation, should
use this macro.


warnmsg( char *format , ... )
	Calls error_message_out(), prepending "Warning:" to the string.


The following macros are only active if 'DEBUG' is defined. If 'DEBUG' is not
defined, they are replaced with a null statement, which most compilers should
optimise away, resulting in no code being generated for the function calls.


trace_functioncall()
	Calls debug_output_f() to print the name of the function it is in.


trace_debug( int level , char *format , ... )
	The usual function called to output debugging information, using
debug_output_f() It saves the developer from having to add __FILE__,
__LINE__,__PRETTY_FUNCTION__ to every call to the debug output function.

	'level' should be one of DEBUGLEVEL_ALWAYS, DEBUGLEVEL_LOW,
DEBUGLEVEL_MEDIUM, DEBUGLEVEL_HIGH, or DEBUGLEVEL_1 to DEBUGLEVEL_10.


temp_trace_debug( format , ... )
	This acts like a trace_debug() with a debug level of 'always'. The
intention is for this to be used for temporary debugging, and either deleted
or commented out once it is no longer needed.


trace_notdone()
	This displays a warning that a function has not been implemented. 


badsecurity_printf()
	This appends the string "SECURITY HOLE:" to debugigng output, and is
intended to help highlight security holes opened by debugging code. This
uses debug_output_f(), which outputs to stderr.


debug_output(int level, char *format , ... )
	This is a 'printf' replacement that directs output to stderr, and only
operates when the debug level is less than or equal to the configured
debuglevel control. It only displays when in DEBUG mode.

