0N/ACopyright (C) 1999-2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")

553N/A

0N/AThis Source Code Form is subject to the terms of the Mozilla Public

0N/ALicense, v. 2.0. If a copy of the MPL was not distributed with this

0N/Afile, You can obtain one at http://mozilla.org/MPL/2.0/.

0N/A

0N/A$Id: results,v 1.7 2004/03/05 05:04:50 marka Exp $

0N/A

0N/AResult Codes

0N/A

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

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

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

0N/Aseems more promising, e.g.

0N/A

0N/A sometype_t s;

0N/A

0N/A sometype_dosomething(s, buffer);

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

553N/A /* ... */

553N/A }

0N/A

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

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

0N/A

0N/A sometype_lock();

0N/A sometype_dosomething(s, buffer);

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

0N/A /* ... */

0N/A }

0N/A sometype_unlock();

0N/A

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

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

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

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

0N/Alocking needs of the routine are.

0N/A

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

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

0N/A

0N/A isc_result_t result;

0N/A

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

0N/A

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

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

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

0N/Afunction's return values separate.

0N/A

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