Copyright (C) 1999-2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")

This Source Code Form is subject to the terms of the Mozilla Public

License, v. 2.0. If a copy of the MPL was not distributed with this

file, You can obtain one at http://mozilla.org/MPL/2.0/.

$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.