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

Copyright (C) 1999-2002 Internet Software Consortium.

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

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

Magic Numbers

A number of data structures in the ISC and DNS libraries have an unsigned int

magic number as the first field. The purpose of the magic number is

principally to validate that a pointer a subroutine has gotten really points

to the type it claims to be. This helps detect problems caused by resources

being freed prematurely, that have been corrupted, or that have not been

properly initialized. It can also be handy in debugging.

Magic numbers should always be the first field. They never require locking

to access. As to the actual value to be used, something mnemonic is good:

#define TASK_MAGIC 0x5441534BU /* TASK. */

#define VALID_TASK(t) ((t) != NULL && \

(t)->magic == TASK_MAGIC)

#define TASK_MANAGER_MAGIC 0x54534B4DU /* TSKM. */

#define VALID_MANAGER(m) ((m) != NULL && \

(m)->magic ==

TASK_MANAGER_MAGIC)

Unless the memory cost is critical, most objects should have a magic number.

The magic number should be the last field set in a creation routine, so that

an object will never be stamped with a magic number unless it is valid.

The magic number should be set to zero immediately before the object is

freed.

Magic values are generally private to the implementation of the type. I.e.

they are defined in the .c file, not the .h file.

Validation of magic numbers is done by routines that manipulate the type,

not by users of the type. Indeed, user validation is usually not possible

because the magic number is not public.

Magic number checking may become a build option in a future release. E.g.

struct foo {

ISC_MAGIC_DECLARATION

/* ... */

}

foo_create() {

/* ... */

ISC_MAGIC_SET(value);

}

foo_destroy() {

/* ... */

ISC_MAGIC_CLEAR(value);

}

#define FOO_MAGIC 0x00010203U

#define VALID_FOO(f) ISC_MAGIC_VALIDATE(f, FOO_MAGIC)

foo_dosomething(foo *f) {

REQUIRE(VALID_FOO(f));

}