unexpected revision 9c3531d72aeaad6c5f01efe6a1c82023e1379e4d
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCopyright (C) 1999, 2000 Internet Software Consortium.
297be3708069ef31814d6d75c0d71a50a78feb03Mark AndrewsSee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein$Id: unexpected,v 1.3 2000/06/22 21:54:08 tale Exp $
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinUnexpected Errors
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor portability, the ISC and DNS libraries define their own result codes
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeininstead of using the operating system's. E.g. the ISC library uses
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinISC_R_NOMEMORY instead of the UNIX-specific ENOMEM.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe ISC and DNS libraries have a common way of looking at errors and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinother non-success results. An "expected" result is something that can
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinhappen in the ordinary course of using a function, that is not very
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinimprobable, and that the caller might care to know. For example, a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfunction which opens a file must have a way to say "file not found"
38417cbfb1a328c20b5b723b8584a02c57f88897Automatic Updaterand "permission denied".
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinOther kinds of errors are "unexpected". For example, an I/O error
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinmight occur. When an unexpected error occurs, we want to be able to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlog the information, but we don't want to translate every
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrewsoperating-system-specific error code into and ISC_R_ or DNS_R_ code
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinbecause the are too many of them, and they aren't meaningful to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinclients anyway (they're unexpected errors). If we were using a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlanguage where we could throw an exception, we'd do that. Since we're
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnot, we call UNEXPECTED_ERROR(). E.g.
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews if (some_unix_thang() < 0) {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein UNEXPECTED_ERROR(__FILE__, __LINE__,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein "some_unix_thang() failed: %s",
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein strerror(errno));
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein return (ISC_R_UNEXPECTED);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe UNEXPECTED error routine may be specified by the calling application. It
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwill log the error somehow (e.g. via. syslog, or printing to stderr).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThis method is a compromise. It makes useful error information available,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinbut avoids the complexity of a more sophisticated multi-library "error table"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinIn the (rare) situation where a library routine encounters a fatal error and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinhas no way of reporting the error to the application, the library may call
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFATAL_ERROR(). This will log the problem and then terminate the application.