Copyright (C) Internet Systems Consortium, Inc. ("ISC")

See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

$Id: unexpected,v 1.6 2004/03/05 05:04:50 marka Exp $

Unexpected Errors

For portability, the ISC and DNS libraries define their own result codes
instead of using the operating system's.  E.g. the ISC library uses
ISC_R_NOMEMORY instead of the UNIX-specific ENOMEM.

The ISC and DNS libraries have a common way of looking at errors and
other non-success results.  An "expected" result is something that can
happen in the ordinary course of using a function, that is not very
improbable, and that the caller might care to know.  For example, a
function which opens a file must have a way to say "file not found"
and "permission denied".

Other kinds of errors are "unexpected".  For example, an I/O error
might occur.  When an unexpected error occurs, we want to be able to
log the information, but we don't want to translate every
operating-system-specific error code into and ISC_R_ or DNS_R_ code
because the are too many of them, and they aren't meaningful to
clients anyway (they're unexpected errors).  If we were using a
language where we could throw an exception, we'd do that.  Since we're
not, we call UNEXPECTED_ERROR().  E.g.

#include <isc/error.h>

void foo() {
	if (some_unix_thang() < 0) {
		UNEXPECTED_ERROR(__FILE__, __LINE__,
				 "some_unix_thang() failed: %s",
				 strerror(errno));
		return (ISC_R_UNEXPECTED);
	}
}

The UNEXPECTED error routine may be specified by the calling application.  It
will log the error somehow (e.g. via. syslog, or printing to stderr).

This method is a compromise.  It makes useful error information available,
but avoids the complexity of a more sophisticated multi-library "error table"
scheme.

In the (rare) situation where a library routine encounters a fatal error and
has no way of reporting the error to the application, the library may call
FATAL_ERROR().  This will log the problem and then terminate the application.