<!--
Copyright (C) Internet Systems Consortium, Inc. ("ISC")

SPDX-License-Identifier: MPL-2.0

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0.  If a copy of the MPL was not distributed with this
file, you can obtain one at https://mozilla.org/MPL/2.0/.

See the COPYRIGHT file distributed with this work for additional
information regarding copyright ownership.
-->

Result Codes

The use of global variables or a GetLastError() function to return results
doesn't work well in a multithreaded application.  The global variable has
obvious problems, as does a global GetLastError().  A per-object GetLastError()
seems more promising, e.g.

	sometype_t s;

	sometype_dosomething(s, buffer);
	if (sometype_error(s)) {
		/* ... */
	}

If 's' is shared however this approach doesn't work unless the locking is
done by the caller, e.g.

	sometype_lock();
	sometype_dosomething(s, buffer);
	if (sometype_error(s)) {
		/* ... */
	}
	sometype_unlock();

Those ISC and DNS libraries which have locks almost universally put the
locking inside of the called routines, since it's more convenient for
the calling programmer, makes for a cleaner API, and puts the burden
of locking on the library programmer, who should know best what the
locking needs of the routine are.

Because of this locking style the ISC and DNS libraries typically provide
result information as the return value of the function.  E.g.

	isc_result_t result;

	result = isc_task_send(task, &event);

Note that an explicit result type is used, instead of mixing the error result
type with the normal result type.  E.g. the C library routine getc() can
return a character or EOF, but the BIND 9 style keeps the types of the
function's return values separate.

	char c;

	result = isc_io_getc(stream, &c);
	if (result == ISC_R_SUCCESS) {
		/* Do something with 'c'. */
	} else if (result == ISC_R_EOF) {
		/* EOF. */
	} else {
		/* Some other error. */
	}

Functions which cannot fail (assuming the caller has provided valid
arguments) need not return a result type.  For example, dns_name_issubdomain()
returns an bool, because it cannot fail.