add

doc/dev/unexpected

@@ -0,0 +1,44 @@
+
+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(__FILE__, __LINE__,
+				 "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.