NAME

       com_err - common error display routine

SYNOPSIS

        #include <et/com_err.h>
       void (*proc) (const char *, long, const char *, va_list);

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

       proc = set_com_err_hook (proc);

       proc = reset_com_err_hook ();

       void initialize_XXXX_error_table ();

DESCRIPTION

       Com_err  displays  an  error  message on the standard error stream stderr (see stdio(3S)) composed of the
       whoami string, which should specify the program name or some subportion of  a  program,  followed  by  an
       error message generated from the code value (derived from compile_et(1)), and a string produced using the
       format string and any following arguments, in the same style as fprintf(3).

       The  behavior of com_err can be modified using set_com_err_hook; this defines a procedure which is called
       with the arguments passed to com_err, instead of the default internal procedure which sends the formatted
       text to error output.  Thus the error messages from a program can all easily be diverted to another  form
       of  diagnostic  logging,  such  as  syslog(3).  Reset_com_err_hook may be used to restore the behavior of
       com_err to its default form.  Both  procedures  return  the  previous  ``hook''  value.   These  ``hook''
       procedures must have the declaration given for proc above in the synopsis.

       The  initialize_XXXX_error_table  routine  is  generated mechanically by compile_et(1) from a source file
       containing names and associated strings.  Each table has a name of up to four characters, which  is  used
       in  place  of  the  XXXX  in  the name of the routine.  These routines should be called before any of the
       corresponding error codes are used, so that the com_err library will recognize  error  codes  from  these
       tables when they are used.

       The  com_err.h  header  file  should  be  included in any source file that uses routines from the com_err
       library; executable files must be linked using ``-lcom_err'' in order to cause the com_err library to  be
       included.

SEE ALSO

       compile_et (1), syslog (3).

       Ken Raeburn, "A Common Error Description Library for UNIX".

SIPB                                               22 Nov 1988                                        COM_ERR(3)