cvs updates from Wed Dec 15 17:45:22 EST 2010

[tridge/bind9.git] / doc / dev / magic_numbers

diff --git a/doc/dev/magic_numbers b/doc/dev/magic_numbers
new file mode 100644 (file)
index 0000000..989c9e8
--- /dev/null
+++ b/doc/dev/magic_numbers
@@ -0,0 +1,65 @@
+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));
+       }