mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-22 18:19:42 +00:00
68 lines
2.2 KiB
Plaintext
68 lines
2.2 KiB
Plaintext
Copyright (C) 1999-2002, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
|
|
|
|
This Source Code Form is subject to the terms of the Mozilla Public
|
|
License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
|
|
$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));
|
|
}
|