bind/doc/dev/unexpected

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

SPDX-License-Identifier: MPL-2.0

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 https://mozilla.org/MPL/2.0/.

See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
-->

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("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.