0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCopyright (C) 1999-2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThis Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsLicense, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsfile, You can obtain one at http://mozilla.org/MPL/2.0/.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews$Id: unexpected,v 1.6 2004/03/05 05:04:50 marka 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.