bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftCopyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftCopyright (C) 1999-2001 Internet Software Consortium.

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift$Id: results,v 1.7 2004/03/05 05:04:50 marka Exp $

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftResult Codes

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftThe use of global variables or a GetLastError() function to return results

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftdoesn't work well in a multithreaded application. The global variable has

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftobvious problems, as does a global GetLastError(). A per-object GetLastError()

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftseems more promising, e.g.

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift sometype_t s;

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift sometype_dosomething(s, buffer);

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift if (sometype_error(s)) {

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift /* ... */

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift }

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftIf 's' is shared however this approach doesn't work unless the locking is

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftdone by the caller, e.g.

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift sometype_lock();

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift sometype_dosomething(s, buffer);

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift if (sometype_error(s)) {

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift /* ... */

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift }

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift sometype_unlock();

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftThose ISC and DNS libraries which have locks almost universally put the

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftlocking inside of the called routines, since it's more convenient for

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftthe calling programmer, makes for a cleaner API, and puts the burden

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftof locking on the library programmer, who should know best what the

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftlocking needs of the routine are.

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftBecause of this locking style the ISC and DNS libraries typically provide

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swiftresult information as the return value of the function. E.g.

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift isc_result_t result;

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift

bb8874d71cdd8e5288297b9727703437c6dfcfedmatthew_swift 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 isc_boolean_t, because it cannot fail.