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

FreeBSD Manual Pages

  
 
  

home | help
COM_ERR(3)	       FreeBSD Library Functions Manual		    COM_ERR(3)

NAME
     com_err, com_err_va, error_message, error_table_name, init_error_table,
     set_com_err_hook, reset_com_err_hook, add_to_error_table,
     initialize_error_table_r free_error_table,	com_right -- common error dis-
     play library

LIBRARY
     Common Error Library (libcom_err, -lcom_err)

SYNOPSIS
     #include <stdio.h>
     #include <stdarg.h>
     #include <com_err.h>
     #include "XXX_err.h"

     typedef void (*errf)(const	char *,	long, const char *, ...);

     void
     com_err(const char	*whoami, long code, const char *format,	...);

     void
     com_err_va(const char *whoami, long code, const char *format, ...);

     const char	*
     error_message(long	code);

     const char	*
     error_table_name(int num);

     int
     init_error_table(const char **msgs, long base, int	count);

     errf
     set_com_err_hook(errf func);

     errf
     reset_com_err_hook();

     void
     add_to_error_table(struct et_list *new_table);

     void
     initialize_error_table_r(struct et_list **et_list,	const char **msgs,
	 int base, long	count);

     void
     free_error_table(struct et_list *);

     const char	*
     com_right(struct et_list *list, long, code");

DESCRIPTION
     The com_err library provides a common error-reporting mechanism for
     defining and accessing error codes	and descriptions for application soft-
     ware packages.  Error descriptions	are defined in a table and error codes
     are used to index the table.  The error table, the	descriptions and the
     error codes are generated using compile_et(1).

     The error table is	registered with	the com_err library by calling its
     initialisation function defined in	its header file.  The initialisation
     function is generally defined as initialize_<name>_error_table(), where
     name is the name of the error table.

     If	a thread-safe version of the library is	needed
     initialize_<name>_error_table_r() that internally calls
     initialize_error_table_r()	instead	be used.

     Any variable which	is to contain an error code should be declared
     _name__error_number where name is the name	of the error table.

FUNCTIONS
     The following functions are available to the application developer:

     com_err(whoami, code, format, ...)
	      Displays an error	message	on standard error composed of the
	      whoami string, which should specify the program name, followed
	      by an error message generated from code, and a string produced
	      using the	printf(3) format string	and any	following arguments.
	      If format	is NULL, the formatted message will not	be printed.
	      The argument format may not be omitted.

     com_err_va(whoami,	code, format, va_list args)
	      This routine provides an interface, equivalent to	com_err(),
	      which may	be used	by higher-level	variadic functions (functions
	      which accept variable numbers of arguments).

     error_message(code)
	      Returns the character string error message associate with	code.
	      If code is associated with an unknown error table, or if code is
	      associated with a	known error table but is not in	the table, a
	      string of	the form `Unknown code XXXX NN'	is returned, where
	      XXXX is the error	table name produced by reversing the com-
	      paction performed	on the error table number implied by that
	      error code, and NN is the	offset from that base value.

	      Although this routine is available for use when needed, its use
	      should be	left to	circumstances which render com_err() unusable.

	      com_right() returns the error string just	like com_err but in a
	      thread-safe way.

     error_table_name(num)
	      Convert a	machine-independent error table	number num into	an
	      error table name.

     init_error_table(msgs, base, count)
	      Initialise the internal error table with the array of character
	      string error messages in msgs of length count.  The error	codes
	      are assigned incrementally from base.  This function is useful
	      for using	the error-reporting mechanism with custom error	tables
	      that have	not been generated with	compile_et(1).	Although this
	      routine is available for use when	needed,	its use	should be
	      restricted.

	      initialize_error_table_r() initialize the	et_list	in the same
	      way as init_error_table(), but in	a thread-safe way.

     set_com_err_hook(func)
	      Provides a hook into the com_err library to allow	the routine
	      func to be dynamically substituted for com_err().	 After
	      set_com_err_hook()
	       has been	called,	calls to com_err() will	turn into calls	to the
	      new hook routine.	 This function is intended to be used in dae-
	      mons to use a routine which calls	syslog(3), or in a window sys-
	      tem application to pop up	a dialogue box.

     reset_com_err_hook()
	      Turns off	the hook set in	set_com_err_hook().

     add_to_error_table(new_table)
	      Add the error table, its messages	strings	and error codes	in
	      new_table	to the internal	error table.

EXAMPLES
     The following is an example using the table defined in compile_et(1):

	     #include <stdio.h>
	     #include <stdarg.h>
	     #include <syslog.h>

	     #include "test_err.h"

	     void
	     hook(const	char *whoami, long code,
		     const char	*format, va_list args)
	     {
		     char buffer[BUFSIZ];
		     static int	initialized = 0;

		     if	(!initialized) {
			     openlog(whoami, LOG_NOWAIT, LOG_DAEMON);
			     initialized = 1;
		     }
		     vsprintf(buffer, format, args);
		     syslog(LOG_ERR, "%s %s", error_message(code), buffer);
	     }

	     int
	     main(int argc, char *argv[])
	     {
		     char *whoami = argv[0];

		     initialize_test_error_table();
		     com_err(whoami, TEST_INVAL, "before hook");
		     set_com_err_hook(hook);
		     com_err(whoami, TEST_IO, "after hook");
		     return (0);
	     }

SEE ALSO
     compile_et(1)

FreeBSD	11.2			 July 7, 2005			  FreeBSD 11.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | FUNCTIONS | EXAMPLES | SEE ALSO

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

home | help