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