A Common Error Description Library for UNIX

Go to the first, previous, next, last section, table of contents.

@barfo

This file documents the use of the Common Error Description library.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B. make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Note that the file texinfo.tex, provided with this distribution, is from the Free Software Foundation, and is under different copyright restrictions from the remainder of this package.

A Common Error Description Library for UNIX

Ken Raeburn Bill Sommerfeld

MIT Student Information Processing Board

last updated 1 January 1989 for version 1.2 ***DRAFT COPY ONLY***

Abstract

UNIX has always had a clean and simple system call interface, with a standard set of error codes passed between the kernel and user programs. Unfortunately, the same cannot be said of many of the libraries layered on top of the primitives provided by the kernel. Typically, each one has used a different style of indicating errors to their callers, leading to a total hodgepodge of error handling, and considerable amounts of work for the programmer. This paper describes a library and associated utilities which allows a more uniform way for libraries to return errors to their callers, and for programs to describe errors and exceptional conditions to their users.

Note that the file texinfo.tex, provided with this distribution, is from the Free Software Foundation, and is under different copyright restrictions from the remainder of this package.

Why com_err?

In building application software packages, a programmer often has to deal with a number of libraries, each of which can use a different error-reporting mechanism. Sometimes one of two values is returned, indicating simply SUCCESS or FAILURE, with no description of errors encountered. Sometimes it is an index into a table of text strings, where the name of the table used is dependent on the library being used when the error is generated; since each table starts numbering at 0 or 1, additional information as to the source of the error code is needed to determine which table to look at. Sometimes no text messages are supplied at all, and the programmer must supply them at any point at which he may wish to report error conditions. Often, a global variable is assigned some value describing the error, but the programmer has to know in each case whether to look at errno, h_errno, the return value from hes_err(), or whatever other variables or routines are specified. And what happens if something in the procedure of examining or reporting the error changes the same variable?

The package we have developed is an attempt to present a common error-handling mechanism to manipulate the most common form of error code in a fashion that does not have the problems listed above.

A list of up to 256 text messages is supplied to a translator we have written, along with the three- to four-character "name" of the error table. The library using this error table need only call a routine generated from this error-table source to make the table "known" to the com_err library, and any error code the library generates can be converted to the corresponding error message. There is also a default format for error codes accidentally returned before making the table known, which is of the form `unknown code foo 32', where `foo' would be the name of the table.

Go to the first, previous, next, last section, table of contents.