286N/ACopyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")

286N/ACopyright (C) 1999-2001 Internet Software Consortium.

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

286N/A

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

286N/A

286N/AUnexpected Errors

286N/A

286N/AFor portability, the ISC and DNS libraries define their own result codes

286N/Ainstead of using the operating system's. E.g. the ISC library uses

286N/AISC_R_NOMEMORY instead of the UNIX-specific ENOMEM.

286N/A

286N/AThe ISC and DNS libraries have a common way of looking at errors and

286N/Aother non-success results. An "expected" result is something that can

286N/Ahappen in the ordinary course of using a function, that is not very

286N/Aimprobable, and that the caller might care to know. For example, a

286N/Afunction which opens a file must have a way to say "file not found"

286N/Aand "permission denied".

286N/A

286N/AOther kinds of errors are "unexpected". For example, an I/O error

286N/Amight occur. When an unexpected error occurs, we want to be able to

286N/Alog the information, but we don't want to translate every

286N/Aoperating-system-specific error code into and ISC_R_ or DNS_R_ code

286N/Abecause the are too many of them, and they aren't meaningful to

286N/Aclients anyway (they're unexpected errors). If we were using a

286N/Alanguage where we could throw an exception, we'd do that. Since we're

286N/Anot, we call UNEXPECTED_ERROR(). E.g.

286N/A

286N/A#include <isc/error.h>

286N/A

286N/Avoid foo() {

286N/A if (some_unix_thang() < 0) {

286N/A UNEXPECTED_ERROR(__FILE__, __LINE__,

286N/A "some_unix_thang() failed: %s",

286N/A strerror(errno));

286N/A return (ISC_R_UNEXPECTED);

286N/A }

286N/A}

286N/A

286N/AThe UNEXPECTED error routine may be specified by the calling application. It

286N/Awill log the error somehow (e.g. via. syslog, or printing to stderr).

286N/A

286N/AThis method is a compromise. It makes useful error information available,

286N/Abut avoids the complexity of a more sophisticated multi-library "error table"

286N/Ascheme.

286N/A

286N/AIn the (rare) situation where a library routine encounters a fatal error and

286N/Ahas no way of reporting the error to the application, the library may call

286N/AFATAL_ERROR(). This will log the problem and then terminate the application.

286N/A