lib/et/com_err.3

   1 .\" Copyright (c) 1988 Massachusetts Institute of Technology,
   2 .\" Student Information Processing Board.
   3 .\"
   4 .TH COM_ERR 3 "22 Nov 1988" SIPB
   5 .SH NAME
   6 com_err \- common error display routine
   7 .SH SYNOPSIS
   8 .nf
   9  #include <et/com_err.h>
  10 .PP
  11 void com_err (whoami, code, format, ...);
  12         const char *whoami;
  13         long code;
  14         const char *format;
  15 .PP
  16 proc = set_com_err_hook (proc);
  17 .fi
  18 void (*
  19 .I proc
  20 ) (const char *, long, const char *, va_list);
  21 .nf
  22 .PP
  23 proc = reset_com_err_hook ();
  24 .PP
  25 void initialize_XXXX_error_table ();
  26 .fi
  27 .SH DESCRIPTION
  28 .I Com_err
  29 displays an error message on the standard error stream
  30 .I stderr
  31 (see
  32 .IR stdio (3S))
  33 composed of the
  34 .I whoami
  35 string, which should specify the program name or some subportion of
  36 a program, followed by an error message generated from the
  37 .I code
  38 value (derived from
  39 .IR compile_et (1)),
  40 and a string produced using the
  41 .I format
  42 string and any following arguments, in the same style as
  43 .IR fprintf (3).
  44
  45 The behavior of
  46 .I com_err
  47 can be modified using
  48 .I set_com_err_hook;
  49 this defines a procedure which is called with the arguments passed to
  50 .I com_err,
  51 instead of the default internal procedure which sends the formatted
  52 text to error output.  Thus the error messages from a program can all
  53 easily be diverted to another form of diagnostic logging, such as
  54 .IR syslog (3).
  55 .I Reset_com_err_hook
  56 may be used to restore the behavior of
  57 .I com_err
  58 to its default form.  Both procedures return the previous ``hook''
  59 value.  These ``hook'' procedures must have the declaration given for
  60 .I proc
  61 above in the synopsis.
  62
  63 The
  64 .I initialize_XXXX_error_table
  65 routine is generated mechanically by
  66 .IR compile_et (1)
  67 from a source file containing names and associated strings.  Each
  68 table has a name of up to four characters, which is used in place of
  69 the
  70 .B XXXX
  71 in the name of the routine.  These routines should be called before
  72 any of the corresponding error codes are used, so that the
  73 .I com_err
  74 library will recognize error codes from these tables when they are
  75 used.
  76
  77 The
  78 .B com_err.h
  79 header file should be included in any source file that uses routines
  80 from the
  81 .I com_err
  82 library; executable files must be linked using
  83 .I ``-lcom_err''
  84 in order to cause the
  85 .I com_err
  86 library to be included.
  87
  88 .\" .IR for manual entries
  89 .\" .PP for paragraph breaks
  90
  91 .SH "SEE ALSO"
  92 compile_et (1), syslog (3).
  93
  94 Ken Raeburn, "A Common Error Description Library for UNIX".