GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  EXPLAIN_OUTPUT (3)

NAME

explain_output - output error messages

CONTENTS

Synopsis
Description
Output Redirection
Copyright
Author

SYNOPSIS

#include <libexplain/output.h>

DESCRIPTION

These functions may be used to write error messages.

    explain_output_message

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 I]explain_output_register(3) for how.
I]text The text of the message to be printed. It has not been wrapped (yet).

    explain_output_error

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

The explain_output_error function is used to print a formatted error message. The printing is done via the I]explain_output_message(3) function.
I]fmt The format text of the message to be printed. See I]printf(3) for more information.

    explain_output_error_and_die

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 I]explain_output_message(3) function, process termination is via the I]explain_output_exit_failure(3) function.
I]fmt The format text of the message to be printed. See printf(3) for more information.

    explain_output_warning

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

The explain_output_warning function is used to print a formatted error message, including the word [lq]warning[rq]. The printing is done via the I]explain_output_message(3) function.
I]fmt The format text of the message to be printed. See I]printf(3) for more information.

    explain_output_exit

void explain_output_exit(int status);

The explain_output_exit function is used to terminate execution. It is executed via the registered output class, I]explain_output_register(3) for how.
I]status The exist status requested.

    explain_output_exit_failure

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, see I]explain_output_register(3) for how.

    explain_option_hanging_indent_set

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 space, similar to RFC822 headers.

This can be set using the [lq]CW]hanging[hy]indent=I]n[rq] string in the EXPLAIN_OPTIONS environment variable. See I]explain(3) for more information.

Using this function will override any environment variable setting.
I]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 too much of each line, and it is a clear indent.

OUTPUT REDIRECTION

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

By default, libexplain will wrap and print error messages on stderr, and call the I]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.
B]syslog To cause all output to be sent to syslog, use

  explain_output_register(explain_output_syslog_new());

This is useful for servers and daemons.

B]stderr and syslog
  The [lq]tee[rq] 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 [lq]tee[rq], cascaded.

B]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)
    )
);


See the CW]<libexplain/output.h> file for extensive documentation.

    explain_output_new

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.
I]vtable The struct containing the pointers to the methods of the derived class.
I]returns
  NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the class.

    explain_output_stderr_new

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 I]exit(2);

This is the default output handler.
I]returns
  NULL on error (i.e. malloc failed), or a pointer to a new dynamically allocated instance of the stderr class.

    explain_output_syslog_new

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 I]exit(2);

The following values are used:


option = 0
facility = LOG_USER
level = LOG_ERR


See I]syslog(3) for more information.
I]returns
  NULL on error (i.e. I]malloc(3) failed), or a pointer to a new dynamically allocated instance of the syslog class.

    explain_output_syslog_new1

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 I]exit(2);

The following values are used:


option = 0
facility = LOG_USER


See I]syslog(3) for more information.
I]level The syslog level to be used, see syslog(3) for a definition.
I]returns
  NULL on error (i.e. I]malloc(3) failed), or a pointer to a new dynamically allocated instance of the syslog class.

    explain_output_syslog_new3

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 I]exit(2);

If you want different facilities or levels, create multiple instances.
I]option The syslog option to be used, see syslog(3) for a definition.
I]facility
  The syslog facility to be used, see syslog(3) for a definition.
I]level The syslog level to be used, see syslog(3) for a definition.
I]returns
  NULL on error (i.e. I]malloc(3) failed), or a pointer to a new dynamically allocated instance of the syslog class.

    explain_output_file_new

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 I]exit(2).
I]filename
  The file to be opened and written to.
I]append true (non[hy]zero) if messages are to be appended to the file, false (zero) if the file is to be replaced with new contents.
I]returns
  NULL on error (i.e. I]malloc(3) or I]open(2) failed), or a pointer to a new dynamically allocated instance of the syslog class.

    explain_output_tee_new

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 B]two other output classes.
I]first The first output class to write to.
I]second The second output class to write to.
I]returns
  NULL on error (i.e. I]malloc(3) failed), or a pointer to a new dynamically allocated instance of the syslog class.
The output subsystem will [lq]own[rq] the I]first and I]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.

    explain_output_register

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 I]exit(2) system call.
I]op Pointer to the explain_output_t instance to be operated on.
The output subsystem will [lq]own[rq] 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.

COPYRIGHT

libexplain version 1.3
Copyright © 2010 Peter Miller

AUTHOR

Written by Peter Miller <pmiller@opensource.org.au>
Search for    or go to Top of page |  Section 3 |  Main Index


EXPLAIN_OUTPUT (3) -->

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.