Output Redirection. More...

#include <libexplain/gcc_attributes.h>

Data Structures
struct	explain_output_t
struct	explain_output_vtable_t
Typedefs
typedef struct explain_output_t	explain_output_t
typedef struct explain_output_vtable_t	explain_output_vtable_t
Functions
explain_output_t *	explain_output_new (const explain_output_vtable_t *vtable)
explain_output_t *	explain_output_stderr_new (void)
explain_output_t *	explain_output_syslog_new (void)
explain_output_t *	explain_output_syslog_new1 (int level)
explain_output_t *	explain_output_syslog_new3 (int option, int facility, int level)
explain_output_t *	explain_output_file_new (const char *filename, int append)
explain_output_t *	explain_output_tee_new (explain_output_t first, explain_output_t second)
void	explain_output_message (const char *text)
void	explain_output_error (const char *fmt,...) LIBEXPLAIN_FORMAT_PRINTF(1
void void	explain_output_error_and_die (const char *fmt,...) LIBEXPLAIN_NORETURN
void	explain_output_warning (const char *fmt,...) LIBEXPLAIN_FORMAT_PRINTF(1
void void	explain_output_method_message (explain_output_t op, const char text)
void	explain_output_exit (int status) LIBEXPLAIN_NORETURN
void	explain_output_exit_failure (void) LIBEXPLAIN_NORETURN
void	explain_output_method_exit (explain_output_t *op, int status) LIBEXPLAIN_NORETURN
void	explain_output_register (explain_output_t *op)
void	explain_output_method_destructor (explain_output_t *op)
void	explain_program_name_assemble (int yesno)
void	explain_option_hanging_indent_set (int columns)

Detailed Description

Output Redirection.

It is possible to change how and where libexplain sends its output, and even how it calls the exit(2) function. This functionality is used by the explain_*_or_die and explain_*_on_error functions.

By default, libexplain will wrap and print error messages on stderr, and call the exit(2) system call to terminate execution.

Clients of the libexplain library may choose to use some message handling facilities provided by libexplain, or they may choose to implement their own.

syslog

To cause all output to be sent to syslog, use

     explain_output_register(explain_output_syslog_new());

"stderr and syslog"

The "tee" output class can be used to duplicate output. To cause all output to be sent to both stderr and syslog, use

     explain_output_register
     (
         explain_output_tee_new
         (
             explain_output_stderr_new(),
             explain_output_syslog_new()
         )
     );

If you need more than two, use several instances of "tee", cascaded.

"stderr and a file"

To cause all output to be sent to both stderr and a regular file, use

     explain_output_register
     (
         explain_output_tee_new
         (
             explain_output_stderr_new(),
             explain_output_file_new(filename, 0)
         )
     );

C++

It would be possible to create an error handler that accumulated a string when its message method was called, and threw an exception when its "exit" method was called. This is why "message" and "exit" are tied together in this way.

FIXME: write such a thing, and include it in the library

Definition in file output.h.

Typedef Documentation

typedef struct explain_output_t explain_output_t

The explain_output_t type is a synonym for struct explain_output_t.

Definition at line 90 of file output.h.

typedef struct explain_output_vtable_t explain_output_vtable_t

The explain_output_vtable_t type is a synonym for struct explain_output_vtable_t.

Definition at line 121 of file output.h.

Function Documentation

void explain_option_hanging_indent_set ( int columns )

The explain_option_hanging_indent_set function is used to cause the output wrapping to use hanging indents. By default no hanging indent is used, but this can sometimes obfuscate the end of one error message and the beginning of another. A hanging indent results in continuation lines starting with white spoace, similar to RFC822 headers.

This can be set using the "hanging-indent=N" string in the EXPLAIN_OPTIONS environment variable.

Using this function will override any environment variable setting.

Parameters:

columns The number of columns of hanging indent to be used. A value of 0 means no hanging indent (all lines flush with left margin). A common value to use is 4: it doesn't consume to much of each line, and it is a clear indent.

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

The explain_output_error function is used to print a formatted error message.

If the program name option has been selected, the program name will be prepended to the error message before it is printed. To select the option

calling the explain_program_name_assemble function at the start of your program's main() function; or,
using the EXPLAIN_OPTIONS environment variable, giving the "program-name" or "no-program-name" option; or,
the default is to print the program name at the start of error and warning messages.

These methods are presented here in order of highest to lowest precedence.

The printing is done via the explain_output_message function, which will do wrapping and indenting if the appropriate output class and options have been selected.

Parameters:

fmt	The format text of the message to be printed. See printf(3) for more information.

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

The explain_output_error_and_die function is used to print text, and then terminate immediately. The printing is done via the explain_output_message function, explain_output_exit function.

Parameters:

fmt	The format text of the message to be printed. See printf(3) for more information.

void explain_output_exit ( int status )

The explain_output_exit function is used to terminate execution. It is executed via the registered output class, explain_output_register for how.

Parameters:

status The exist status requested.

void explain_output_exit_failure ( void )

The explain_output_exit_failure function is used to terminate execution, with exit status EXIT_FAILURE. It is executed via the registered output class, explain_output_register for how.

explain_output_t* explain_output_file_new	(	const char *	filename,
		int	append
	)

The explain_output_file_new function may be used to create a new dynamically allocated instance of an explain_output_t class that writes to a file, and exits via exit(2).

Parameters:

filename	The file to be oopened and written to.
append	true (non-zero) if messages are to be appended to the file, false (zero) if the file is to be preplaced with new contents.

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the syslog class.

void explain_output_message ( const char * text )

The explain_output_message function is used to print text. It is printed via the registered output class, see explain_output_register for how.

Parameters:

text	The text of the message to be printed. It has not been wrapped.

void explain_output_method_destructor ( explain_output_t * op )

The explain_output_method_destructor function is used to destroy an output instance, when its lifetime is over, think of it as a class specific free() function. It is called by explain_output_register when a new output instance is given.

It is safe for op to be NULL. It is safe for op->vtable->destructor to be NULL.

Parameters:

op	Pointer to the explain_output_t instance to be operated on.

void explain_output_method_exit	(	explain_output_t *	op,
		int	status
	)

The explain_output_method_exit function is used to terminate execution. Different "classes" handle this differently.

Parameters:

op	Pointer to the explain_output_t instance to be operated on.
status	The exist status requested.

void void explain_output_method_message	(	explain_output_t *	op,
		const char *	text
	)

The explain_output_method_message function is used to print text. Different output "classes" handle this differently.

Parameters:

op	Pointer to the explain_output_t instance to be "printed" on.
text	The text of the message to be printed. It has not been wrapped.

explain_output_t* explain_output_new ( const explain_output_vtable_t * vtable )

The explain_output_new function may be used to create a new dynamically allocated instance of explain_output_t.

Parameters:

vtable The struct containing the pointers to the methods of the derived class.

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the class.

void explain_output_register ( explain_output_t * op )

The explain_output_register function is used to change libexplain's default output handling facilities with something else. The NULL pointer restores libexplain's default processing.

If no output class is registered, the default is to wrap and print to stderr, and to exit via the exit(2) system call.

Parameters:

op	Pointer to the explain_output_t instance to be operated on. The NULL pointer will reset to the default style (stderr).

Note:: The output subsystem will "own" the pointer after this call. You may not make any reference to this pointer ever again. The output subsystem will destroy the object and free the memory when it feels like it.

explain_output_t* explain_output_stderr_new ( void )

The explain_output_stderr_new function may be used to create a new dynamically allocated instance of an explain_output_t class that writes to stderr, and exits via exit(2);

This is the default output handler.

Long error messages will be wrapped to fit the size of the current terminal line.

You can select whether or not the second and subsequent lines of wrapped error messages are indented.

calling the explain_option_hanging_indent_set function at the beginning of main(); or,
setting the EXPLAIN_OPTIONS environment variable, setting the "hanging-indent=N" option; or,
the default is not to indent the second and subsequent lines of wrapped error messages.

The above list is in order of highest precedence to lowest. A hanging indent of zero means "no indent".

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the stderrr class.

explain_output_t* explain_output_syslog_new ( void )

The explain_output_syslog_new function may be used to create a new dynamically allocated instance of an explain_output_t class that writes to syslog, and exits via exit(2);

The following values are used:
option = 0
facility = LOG_USER
level = LOG_ERR
See syslog(3) for more information.

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the syslog class.

explain_output_t* explain_output_syslog_new1 ( int level )

The explain_output_syslog_new1 function may be used to create a new dynamically allocated instance of an explain_output_t class that writes to syslog, and exits via exit(2);

The following values are used:
option = 0
facility = LOG_USER
See syslog(3) for more information.

Parameters:

level The syslog level to be used, see syslog(3) for a definition.

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the syslog class.

explain_output_t* explain_output_syslog_new3	(	int	option,
		int	facility,
		int	level
	)

The explain_output_syslog_new3 function may be used to create a new dynamically allocated instance of an explain_output_t class that writes to syslog, and exits via exit(2);

If you want different facilities or levels, create multiple instances.

Parameters:

option	The syslog option to be used, see syslog(3) for a definition.
facility	The syslog facility to be used, see syslog(3) for a definition.
level	The syslog level to be used, see syslog(3) for a definition.

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the syslog class.

explain_output_t* explain_output_tee_new	(	explain_output_t *	first,
		explain_output_t *	second
	)

The explain_output_tee_new function may be used to create a new dynamically allocated instance of an explain_output_t class that writes to two other output classes.

Parameters:

first	The first output class to write to.
second	The second output class to write to.

Returns:: NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the syslog class.

Note:: The output subsystem will "own" the first and second objects after this call. You may not make any reference to these pointers ever again. The output subsystem will destroy these objects and free the memory when it feels like it.

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

The explain_output_warning function is used to print a formatted error message, including the word "warning".

If the program name option has been selected, the program name will be prepended to the error message before it is printed. To select the option

call the explain_program_name_assemble function at the start of your program's main() function; or,
use the EXPLAIN_OPTIONS environment variable, giving the "program-name" or "no-program-name" option; or,
the default is to always print the program name at the start of error and warning messages.

These methods are presented here in order of highest to lowest precedence.

The printing is done via the explain_output_message function, which will do wrapping and indenting if the appropriate output class and options have been selected.

Parameters:

fmt	The format text of the message to be printed. See printf(3) for more information.

void explain_program_name_assemble ( int yesno )

The explain_option_assemble_program_name_set option is used to override any EXPLAIN_OPTIONS or default setting as to whether or not the explain_output_error, explain_output_error_and_die and explain_output_warning functions should include the program name at the start the messages.

Parameters:

yesno true (non-zero) to include the program name, zero (false) to omit the program name.

Data Structures

Typedefs

Functions

Detailed Description

syslog

"stderr and syslog"

"stderr and a file"

C++

Typedef Documentation

Function Documentation