Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
explain_output(3)	   Library Functions Manual	     explain_output(3)

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) func-
       tion.

       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_out-
       put_message(3)  function,  process  termination is via the explain_out-
       put_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	execu-
       tion, 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_OP-
       TIONS 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 han-
       dling facilities	provided by libexplain,	or they	may choose  to	imple-
       ment 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", cas-
	       caded.

       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  de-
	       rived class.

       returns NULL  on	 error (i.e. malloc failed), or	a pointer to a new dy-
	       namically 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  dy-
       namically  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  dy-
	       namically 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 dy-
       namically 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 dy-
       namically  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 dy-
       namically  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 ap-
       pend);

       The explain_output_file_new function may	be used	to create a new	dynam-
       ically 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, ex-
       plain_output_t *second);

       The explain_output_tee_new function may be used to create a new dynami-
       cally 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 de-
       fault 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 subsys-
       tem will	destroy	the object and free the	memory when it feels like it.

COPYRIGHT
       libexplain version 1.3
       Copyright (C) 2010 Peter	Miller

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

							     explain_output(3)

NAME | SYNOPSIS | DESCRIPTION | OUTPUT REDIRECTION | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=explain_output&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help