contrib/com_err/com_err.3

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