unexpected revision 9c3531d72aeaad6c5f01efe6a1c82023e1379e4d
9bff67898d55cddfcec9ce30cc2b1bb6211ec691David LawrenceCopyright (C) 1999, 2000 Internet Software Consortium.
9bff67898d55cddfcec9ce30cc2b1bb6211ec691David LawrenceSee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.
9c3531d72aeaad6c5f01efe6a1c82023e1379e4dDavid Lawrence$Id: unexpected,v 1.3 2000/06/22 21:54:08 tale Exp $
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyUnexpected Errors
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyFor portability, the ISC and DNS libraries define their own result codes
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyinstead of using the operating system's. E.g. the ISC library uses
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyISC_R_NOMEMORY instead of the UNIX-specific ENOMEM.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe ISC and DNS libraries have a common way of looking at errors and
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyother non-success results. An "expected" result is something that can
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyhappen in the ordinary course of using a function, that is not very
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyimprobable, and that the caller might care to know. For example, a
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyfunction which opens a file must have a way to say "file not found"
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyand "permission denied".
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyOther kinds of errors are "unexpected". For example, an I/O error
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleymight occur. When an unexpected error occurs, we want to be able to
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleylog the information, but we don't want to translate every
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyoperating-system-specific error code into and ISC_R_ or DNS_R_ code
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleybecause the are too many of them, and they aren't meaningful to
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyclients anyway (they're unexpected errors). If we were using a
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleylanguage where we could throw an exception, we'd do that. Since we're
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleynot, we call UNEXPECTED_ERROR(). E.g.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (some_unix_thang() < 0) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley UNEXPECTED_ERROR(__FILE__, __LINE__,
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley "some_unix_thang() failed: %s",
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley strerror(errno));
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley return (ISC_R_UNEXPECTED);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe UNEXPECTED error routine may be specified by the calling application. It
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleywill log the error somehow (e.g. via. syslog, or printing to stderr).
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThis method is a compromise. It makes useful error information available,
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleybut avoids the complexity of a more sophisticated multi-library "error table"
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyIn the (rare) situation where a library routine encounters a fatal error and
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyhas no way of reporting the error to the application, the library may call
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyFATAL_ERROR(). This will log the problem and then terminate the application.