lib/libcom_err/com_err.7

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "COM_ERR 7"
 136 .TH COM_ERR 7 "2015-04-03" "perl v5.18.4" "DragonFly Miscellaneous Information Manual"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 com_err Manual \- Conversion of com_err.info
 143 .SH "General Introduction"
 144 .IX Header "General Introduction"
 145 * Menu:
 146 .PP
 147 What is all this for?: see \*(L"Why com_err?\*(R"
 148 .PP
 149 What's an error code, anyway?: see \*(L"Error codes\*(R"
 150 .PP
 151 How to describe an error table.: see \*(L"Error table source file\*(R"
 152 .PP
 153 How to compile the table.: see \*(L"The error-table compiler\*(R"
 154 .PP
 155 How to use from within your program.: see \*(L"Run-time support routines\*(R"
 156 .PP
 157 Stylistic issues.: see \*(L"Coding Conventions\*(R"
 158 .PP
 159 How to build and install.: see \*(L"Building and Installation\*(R"
 160 .PP
 161 You have found a bug?  Report it.: see \*(L"Bug Reports\*(R"
 162 .PP
 163 Whom to thank...: see \*(L"Acknowledgements\*(R"
 164 .SS "Why com_err?"
 165 .IX Subsection "Why com_err?"
 166 In building application software packages, a programmer often has to
 167 deal with a number of libraries, each of which can use a different
 168 error-reporting mechanism.  Sometimes one of two values is returned,
 169 indicating simply \s-1SUCCESS\s0 or \s-1FAILURE,\s0 with no description of errors
 170 encountered.  Sometimes it is an index into a table of text strings,
 171 where the name of the table used is dependent on the library being used
 172 when the error is generated; since each table starts numbering at 0 or
 173 1, additional information as to the source of the error code is needed
 174 to determine which table to look at.  Sometimes no text messages are
 175 supplied at all, and the programmer must supply them at any point at
 176 which he may wish to report error conditions.  Often, a global variable
 177 is assigned some value describing the error, but the programmer has to
 178 know in each case whether to look at `\fBerrno\fR', `\fBh_errno\fR', the return
 179 value from `\fB\f(BIhes_err()\fB\fR', or whatever other variables or routines are
 180 specified.  And what happens if something in the procedure of examining
 181 or reporting the error changes the same variable?
 182 .PP
 183 The package we have developed is an attempt to present a common
 184 error-handling mechanism to manipulate the most common form of error
 185 code in a fashion that does not have the problems listed above.
 186 .PP
 187 A list of up to 256 text messages is supplied to a translator we have
 188 written, along with the three\- to four-character \*(L"name\*(R" of the error
 189 table.  The library using this error table need only call a routine
 190 generated from this error-table source to make the table \*(L"known\*(R" to the
 191 com_err library, and any error code the library generates can be
 192 converted to the corresponding error message.  There is also a default
 193 format for error codes accidentally returned before making the table
 194 known, which is of the form `\fBunknown code foo 32\fR', where `\fBfoo\fR' would be
 195 the name of the table.
 196 .SS "Error codes"
 197 .IX Subsection "Error codes"
 198 Error codes themselves are 32 bit (signed) integers, of which the high
 199 order 24 bits are an identifier of which error table the error code is
 200 from, and the low order 8 bits are a sequential error number within the
 201 table.  An error code may thus be easily decomposed into its component
 202 parts.  Only the lowest 32 bits of an error code are considered
 203 significant on systems which support wider values.
 204 .PP
 205 Error table 0 is defined to match the \s-1UNIX\s0 system call error table
 206 (`\fBsys_errlist\fR'); this allows `\fBerrno\fR' values to be used directly in the
 207 library (assuming that `\fBerrno\fR' is of a type with the same width as
 208 long).  Other error table numbers are formed by compacting together the
 209 first four characters of the error table name.  The mapping between
 210 characters in the name and numeric values in the error code are defined
 211 in a system-independent fashion, so that two systems that can pass
 212 integral values between them can reliably pass error codes without loss
 213 of meaning; this should work even if the character sets used are not
 214 the same.  (However, if this is to be done, error table 0 should be
 215 avoided, since the local system call error tables may differ.)
 216 .PP
 217 Any variable which is to contain an error code should be declared
 218 long.  The draft proposed American National Standard for C (as of May,
 219 1988) requires that long variables be at least 32 bits; any system
 220 which does not support 32\-bit long values cannot make use of this
 221 package (nor much other software that assumes an ANSI-C environment
 222 base) without significant effort.
 223 .SS "Error table source file"
 224 .IX Subsection "Error table source file"
 225 The error table source file begins with the declaration of the table
 226 name, as
 227 .PP
 228 error_table \s-1TABLENAME\s0
 229 .PP
 230 Individual error codes are specified with
 231 .PP
 232 error_code \s-1ERROR_NAME, \*(L"TEXT MESSAGE\*(R"\s0
 233 .PP
 234 where `\fBec\fR' can also be used as a short form of `\fBerror_code\fR'.  To
 235 indicate the end of the table, use `\fBend\fR'.  Thus, a (short) sample error
 236 table might be:
 237 .PP
 238 error_table     dsc
 239 .PP
 240 error_code      \s-1DSC_DUP_MTG_NAME,
 241 \&\s0\*(L"Meeting already exists\*(R"
 242 .PP
 243 ec              \s-1DSC_BAD_PATH,
 244 \&\*(L"A\s0 bad meeting pathname was given\*(R"
 245 .PP
 246 ec              \s-1DSC_BAD_MODES,
 247 \&\s0\*(L"Invalid mode for this access control list\*(R"
 248 .PP
 249 end
 250 .SS "The error-table compiler"
 251 .IX Subsection "The error-table compiler"
 252 The error table compiler is named `\fBcompile_et\fR'.  It takes one argument,
 253 the pathname of a file (ending in `\fB.et\fR', e.g., `\fBdsc_err.et\fR') containing
 254 an error table source file.  It parses the error table, and generates
 255 two output files \- a C header file (`\fBdiscuss_err.h\fR') which contains
 256 definitions of the numerical values of the error codes defined in the
 257 error table, and a C source file which should be compiled and linked
 258 with the executable.  The header file must be included in the source of
 259 a module which wishes to reference the error codes defined; the object
 260 module generated from the C code may be linked in to a program which
 261 wishes to use the printed forms of the error codes.
 262 .PP
 263 This translator accepts a `\fB\-language \s-1LANG\s0\fR' argument, which
 264 determines for which language (or language variant) the output should be
 265 written.  At the moment, \s-1LANG\s0 is currently limited to `\fBANSI-C\fR' and
 266 `\fBK&R\-C\fR', and some abbreviated forms of each.  Eventually, this will be
 267 extended to include some support for \*(C+.  The default is currently
 268 `\fBK&R\-C\fR', though the generated sources will have ANSI-C code
 269 conditionalized on the symbol _\|_STDC_\|_.
 270 .SS "Run-time support routines"
 271 .IX Subsection "Run-time support routines"
 272 Any source file which uses the routines supplied with or produced by the
 273 com_err package should include the header file `\fB<com_err.h>\fR'.  It
 274 contains declarations and definitions which may be needed on some
 275 systems.  (Some functions cannot be referenced properly without the
 276 return type declarations in this file.  Some functions may work
 277 properly on most architectures even without the header file, but
 278 relying on this is not recommended.)
 279 .PP
 280 The run-time support routines and variables provided via this package
 281 include the following:
 282 .PP
 283 void initialize_XXXX_error_table (void);
 284 .PP
 285 One of these routines is built by the error compiler for each error
 286 table.  It makes the \s-1XXXX\s0 error table \*(L"known\*(R" to the error reporting
 287 system.  By convention, this routine should be called in the
 288 initialization routine of the \s-1XXXX\s0 library.  If the library has no
 289 initialization routine, some combination of routines which form the
 290 core of the library should ensure that this routine is called.  It is
 291 not advised to leave it the caller to make this call.
 292 .PP
 293 There is no harm in calling this routine more than once.
 294 .PP
 295 #define \s-1ERROR_TABLE_BASE_XXXX NNNNNL\s0
 296 .PP
 297 This symbol contains the value of the first error code entry in the
 298 specified table.  This rarely needs be used by the programmer.
 299 .PP
 300 const char *error_message (long code);
 301 .PP
 302 This routine returns the character string error message associated
 303 with `\fBcode\fR'; if this is associated with an unknown error table, or if
 304 the code is associated with a known error table but the code is not in
 305 the table, a string of the form `\fBUnknown code \s-1XXXX NN\s0\fR' is returned,
 306 where \s-1XXXX\s0 is the error table name produced by reversing the compaction
 307 performed on the error table number implied by that error code, and \s-1NN\s0
 308 is the offset from that base value.
 309 .PP
 310 Although this routine is available for use when needed, its use
 311 should be left to circumstances which render `\fBcom_err\fR' (below) unusable.
 312 .PP
 313 void com_err (const char *whoami,  /* module reporting error */
 314 long code,           /* error code */
 315 const char *format,  /* format for additional detail */
 316 \&...);                /*  (extra parameters) */
 317 .PP
 318 This routine provides an alternate way to print error messages to
 319 standard error; it allows the error message to be passed in as a
 320 parameter, rather than in an external variable.  _Provide grammatical
 321 context for \*(L"message.\*(R"_
 322 .PP
 323 If \s-1FORMAT\s0 is `\fB(char *)NULL\fR', the formatted message will not be
 324 printed.  \s-1FORMAT\s0 may not be omitted.
 325 .PP
 326 #include <stdarg.h>
 327 .PP
 328 void com_err_va (const char *whoami,
 329 long code,
 330 const char *format,
 331 va_list args);
 332 .PP
 333 This routine provides an interface, equivalent to `\fBcom_err\fR' above,
 334 which may be used by higher-level variadic functions (functions which
 335 accept variable numbers of arguments).
 336 .PP
 337 #include <stdarg.h>
 338 .PP
 339 void (*set_com_err_hook (void (*proc) ())) ();
 340 .PP
 341 void (*PROC) (const char *whoami, long code, va_list args);
 342 .PP
 343 void reset_com_err_hook ();
 344 .PP
 345 These two routines allow a routine to be dynamically substituted for
 346 `\fBcom_err\fR'.  After `\fBset_com_err_hook\fR' has been called, calls to
 347 `\fBcom_err\fR' will turn into calls to the new hook routine.
 348 `\fBreset_com_err_hook\fR' turns off this hook.  This may intended to be used
 349 in daemons (to use a routine which calls \s-1\fISYSLOG\s0\fR\|(3)), or in a window
 350 system application (which could pop up a dialogue box).
 351 .PP
 352 If a program is to be used in an environment in which simply printing
 353 messages to the `\fBstderr\fR' stream would be inappropriate (such as in a
 354 daemon program which runs without a terminal attached),
 355 `\fBset_com_err_hook\fR' may be used to redirect output from `\fBcom_err\fR'.  The
 356 following is an example of an error handler which uses \s-1\fISYSLOG\s0\fR\|(3) as
 357 supplied in \s-1BSD 4.3:\s0
 358 .PP
 359 #include <stdio.h>
 360 #include <stdarg.h>
 361 #include <syslog.h>
 362 .PP
 363 /* extern openlog (const char * name, int logopt, int facility); */
 364 /* extern syslog (int priority, char * message, ...); */
 365 .PP
 366 void hook (const char * whoami, long code,
 367 const char * format, va_list args)
 368 {
 369 char buffer[\s-1BUFSIZ\s0];
 370 static int initialized = 0;
 371 if (!initialized) {
 372 openlog (whoami,
 373 LOG_NOWAIT|LOG_CONS|LOG_PID|LOG_NDELAY,
 374 \&\s-1LOG_DAEMON\s0);
 375 initialized = 1;
 376 }
 377 vsprintf (buffer, format, args);
 378 syslog (\s-1LOG_ERR, \s0\*(L"%s \f(CW%s\fR\*(R", error_message (code), buffer);
 379 }
 380 .PP
 381 After making the call `\fBset_com_err_hook (hook);\fR', any calls to
 382 `\fBcom_err\fR' will result in messages being sent to the \s-1SYSLOGD\s0 daemon for
 383 logging.  The name of the program, `\fBwhoami\fR', is supplied to the
 384 `\fB\f(BIopenlog()\fB\fR' call, and the message is formatted into a buffer and passed
 385 to `\fBsyslog\fR'.
 386 .PP
 387 Note that since the extra arguments to `\fBcom_err\fR' are passed by
 388 reference via the `\fBva_list\fR' value `\fBargs\fR', the hook routine may place
 389 any form of interpretation on them, including ignoring them.  For
 390 consistency, `\fBprintf\fR'\-style interpretation is suggested, via `\fBvsprintf\fR'
 391 (or `\fB_doprnt\fR' on \s-1BSD\s0 systems without full support for the \s-1ANSI C\s0
 392 library).
 393 .SS "Coding Conventions"
 394 .IX Subsection "Coding Conventions"
 395 The following conventions are just some general stylistic conventions
 396 to follow when writing robust libraries and programs.  Conventions
 397 similar to this are generally followed inside the \s-1UNIX\s0 kernel and most
 398 routines in the Multics operating system.  In general, a routine either
 399 succeeds (returning a zero error code, and doing some side effects in
 400 the process), or it fails, doing minimal side effects; in any event,
 401 any invariant which the library assumes must be maintained.
 402 .PP
 403 In general, it is not in the domain of non user-interface library
 404 routines to write error messages to the user's terminal, or halt the
 405 process.  Such forms of \*(L"error handling\*(R" should be reserved for
 406 failures of internal invariants and consistancy checks only, as it
 407 provides the user of the library no way to clean up for himself in the
 408 event of total failure.
 409 .PP
 410 Library routines which can fail should be set up to return an error
 411 code.  This should usually be done as the return value of the function;
 412 if this is not acceptable, the routine should return a \*(L"null\*(R" value,
 413 and put the error code into a parameter passed by reference.
 414 .PP
 415 Routines which use the first style of interface can be used from
 416 user-interface levels of a program as follows:
 417 .PP
 418 {
 419 if ((code = initialize_world(\fIgetuid()\fR, \fIrandom()\fR)) != 0) {
 420 com_err(\*(L"demo\*(R", code,
 421 \&\*(L"when trying to initialize world\*(R");
 422 \&\fIexit\fR\|(1);
 423 }
 424 if ((database = open_database(\*(L"my_secrets\*(R", &code))==NULL) {
 425 com_err(\*(L"demo\*(R", code,
 426 \&\*(L"while opening my_secrets\*(R");
 427 \&\fIexit\fR\|(1);
 428 }
 429 }
 430 .PP
 431 A caller which fails to check the return status is in error.  It is
 432 possible to look for code which ignores error returns by using lint;
 433 look for error messages of the form \*(L"foobar returns value which is
 434 sometimes ignored\*(R" or \*(L"foobar returns value which is always ignored.\*(R"
 435 .PP
 436 Since libraries may be built out of other libraries, it is often
 437 necessary for the success of one routine to depend on another.  When a
 438 lower level routine returns an error code, the middle level routine has
 439 a few possible options.  It can simply return the error code to its
 440 caller after doing some form of cleanup, it can substitute one of its
 441 own, or it can take corrective action of its own and continue normally.
 442 For instance, a library routine which makes a \*(L"connect\*(R" system call to
 443 make a network connection may reflect the system error code
 444 `\fB\s-1ECONNREFUSED\s0\fR' (Connection refused) to its caller, or it may return a
 445 \&\*(L"server not available, try again later,\*(R" or it may try a different
 446 server.
 447 .PP
 448 Cleanup which is typically necessary may include, but not be limited
 449 to, freeing allocated memory which will not be needed any more,
 450 unlocking concurrancy locks, dropping reference counts, closing file
 451 descriptors, or otherwise undoing anything which the procedure did up
 452 to this point.  When there are a lot of things which can go wrong, it
 453 is generally good to write one block of error-handling code which is
 454 branched to, using a goto, in the event of failure.  A common source of
 455 errors in \s-1UNIX\s0 programs is failing to close file descriptors on error
 456 returns; this leaves a number of \*(L"zombied\*(R" file descriptors open, which
 457 eventually causes the process to run out of file descriptors and fall
 458 over.
 459 .PP
 460 {
 461 \&\s-1FILE\s0 *f1=NULL, *f2=NULL, *f3=NULL;
 462 int status = 0;
 463 .PP
 464 if ( (f1 = fopen(\s-1FILE1, \s0\*(L"r\*(R")) == \s-1NULL\s0) {
 465 status = errno;
 466 goto error;
 467 }
 468 .PP
 469 /*
 470 * Crunch for a while
 471 */
 472 .PP
 473 if ( (f2 = fopen(\s-1FILE2, \s0\*(L"w\*(R")) == \s-1NULL\s0) {
 474 status = errno;
 475 goto error;
 476 }
 477 .PP
 478 if ( (f3 = fopen(\s-1FILE3, \s0\*(L"a+\*(R")) == \s-1NULL\s0) {
 479 status = errno;
 480 goto error;
 481 }
 482 .PP
 483 /*
 484 * Do more processing.
 485 */
 486 fclose(f1);
 487 fclose(f2);
 488 fclose(f3);
 489 return 0;
 490 .PP
 491 error:
 492 if (f1) fclose(f1);
 493 if (f2) fclose(f2);
 494 if (f3) fclose(f3);
 495 return status;
 496 }
 497 .SS "Building and Installation"
 498 .IX Subsection "Building and Installation"
 499 The distribution of this package will probably be done as a compressed
 500 \&\*(L"tar\*(R"\-format file available via anonymous \s-1FTP\s0 from \s-1SIPB.MIT.EDU.\s0
 501 Retrieve `\fBpub/com_err.tar.Z\fR' and extract the contents.  A subdirectory
 502 profiled should be created to hold objects compiled for profiling.
 503 Running \*(L"make all\*(R" should then be sufficient to build the library and
 504 error-table compiler.  The files `\fBlibcom_err.a\fR', `\fBlibcom_err_p.a\fR',
 505 `\fBcom_err.h\fR', and `\fBcompile_et\fR' should be installed for use; `\fBcom_err.3\fR'
 506 and `\fBcompile_et.1\fR' can also be installed as manual pages.
 507 .PP
 508 Potential problems:
 509 .PP
 510 * Use of `\fBstrcasecmp\fR', a routine provided in \s-1BSD\s0 for
 511 case-insensitive string comparisons.  If an equivalent routine is
 512 available, you can modify `\fB\s-1CFLAGS\s0\fR' in the makefile to define
 513 `\fBstrcasecmp\fR' to the name of that routine.
 514 .PP
 515 * Compilers that defined `\fB_\|_STDC_\|_\fR' without providing the header
 516 file `\fB<stdarg.h>\fR'.  One such example is Metaware's High \*(L"C\*(R"
 517 compiler, as provided at Project Athena on the \s-1IBM RT/PC\s0
 518 workstation; if `\fB_\|_HIGHC_\|_\fR' is defined, it is assumed that
 519 `\fB<stdarg.h>\fR' is not available, and therefore `\fB<varargs.h>\fR' must be
 520 used.  If the symbol `\fB\s-1VARARGS\s0\fR' is defined (e.g., in the makefile),
 521 `\fB<varargs.h>\fR' will be used.
 522 .PP
 523 * If your linker rejects symbols that are simultaneously defined in
 524 two library files, edit `\fBMakefile\fR' to remove `\fBperror.c\fR' from the
 525 library.  This file contains a version of \s-1\fIPERROR\s0\fR\|(3) which calls
 526 `\fBcom_err\fR' instead of calling `\fBwrite\fR' directly.
 527 .PP
 528 As I do not have access to non-BSD systems, there are probably bugs
 529 present that may interfere with building or using this package on other
 530 systems.  If they are reported to me, they can probably be fixed for
 531 the next version.
 532 .SS "Bug Reports"
 533 .IX Subsection "Bug Reports"
 534 Please send any comments or bug reports to the principal author: Ken
 535 Raeburn, Raeburn@Athena.MIT.EDU.
 536 .SS "Acknowledgements"
 537 .IX Subsection "Acknowledgements"
 538 I would like to thank: Bill Sommerfeld, for his help with some of this
 539 documentation, and catching some of the bugs the first time around;
 540 Honeywell Information Systems, for not killing off the _Multics_
 541 operating system before I had an opportunity to use it; Honeywell's
 542 customers, who persuaded them not to do so, for a while; Ted Anderson of
 543 \&\s-1CMU,\s0 for catching some problems before version 1.2 left the nest; Stan
 544 Zanarotti and several others of \s-1MIT\s0's Student Information Processing
 545 Board, for getting us started with \*(L"discuss,\*(R" for which this package was
 546 originally written; and everyone I've talked into \*(-- I mean, asked to
 547 read this document and the \*(L"man\*(R" pages.