Provided by: explain_0.52.D002-1_amd64 bug

NAME

       explain_output - output error messages

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 explain_output_register(3) for how.

       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 explain_output_message(3) function.

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

       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 “warning”.  The printing is done via the explain_output_message(3) function.

       fmt     The format text of the message to be printed.  See 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, explain_output_register(3) for how.

       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
       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 “hanging‐indent=n” string  in  the  EXPLAIN_OPTIONS  environment
       variable.  See explain(3) for more information.

       Using this function will override any environment variable setting.

       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  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());

               This is useful for servers and daemons.

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

       See the <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.

       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.

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

       This is the default output handler.

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

       The following values are used:

              option = 0
              facility = LOG_USER

       See syslog(3) for more information.

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

       returns NULL on error (i.e. 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 exit(2);

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

       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(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 exit(2).

       filename
               The file to be opened and written to.

       append  true  (non‐zero)  if  messages are to be appended to the file, false (zero) if the
               file is to be replaced with new contents.

       returns NULL on error  (i.e.  malloc(3)  or  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 two other output classes.

       first   The first output class to write to.

       second  The second output class to write to.

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

       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.

   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 exit(2) system call.

       op      Pointer to the explain_output_t instance to be operated on.

       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.

COPYRIGHT

       libexplain version 0.52
       Copyright (C) 2010 Peter Miller

AUTHOR

       Written by Peter Miller <pmiller@opensource.org.au>

                                                                                explain_output(3)