970N/ACopyright (C) 1999, 2000 Internet Software Consortium.

1162N/ASee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.

970N/A

970N/A$Id: results,v 1.3 2000/06/22 21:54:07 tale Exp $

970N/A

970N/AResult Codes

970N/A

970N/AThe use of global variables or a GetLastError() function to return results

970N/Adoesn't work well in a multithreaded application. The global variable has

970N/Aobvious problems, as does a global GetLastError(). A per-object GetLastError()

970N/Aseems more promising, e.g.

970N/A

970N/A sometype_t s;

970N/A

970N/A sometype_dosomething(s, buffer);

970N/A if (sometype_error(s)) {

970N/A /* ... */

970N/A }

970N/A

970N/AIf 's' is shared however this approach doesn't work unless the locking is

970N/Adone by the caller, e.g.

970N/A

970N/A sometype_lock();

970N/A sometype_dosomething(s, buffer);

970N/A if (sometype_error(s)) {

970N/A /* ... */

970N/A }

970N/A sometype_unlock();

970N/A

972N/AThose ISC and DNS libraries which have locks almost universally put the

972N/Alocking inside of the called routines, since it's more convenient for

972N/Athe calling programmer, makes for a cleaner API, and puts the burden

972N/Aof locking on the library programmer, who should know best what the

972N/Alocking needs of the routine are.

972N/A

972N/ABecause of this locking style the ISC and DNS libraries typically provide

972N/Aresult information as the return value of the function. E.g.

970N/A

970N/A isc_result_t result;

970N/A

970N/A result = isc_task_send(task, &event);

970N/A

970N/ANote that an explicit result type is used, instead of mixing the error result

1162N/Atype with the normal result type. E.g. the C library routine getc() can

970N/Areturn a character or EOF, but the BIND 9 style keeps the types of the

1162N/Afunction's return values separate.

970N/A

970N/A char c;

970N/A

970N/A result = isc_io_getc(stream, &c);

970N/A if (result == ISC_R_SUCCESS) {

970N/A /* Do something with 'c'. */

970N/A } 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.