magic_numbers revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
f743002678eb67b99bbc29fee116b65d9530fec0wroweCopyright (C) 1999-2002, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
a34684a59b60a4173c25035d0c627ef17e6dc215rpluemThis Source Code Form is subject to the terms of the Mozilla Public
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavicLicense, v. 2.0. If a copy of the MPL was not distributed with this
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavicfile, You can obtain one at http://mozilla.org/MPL/2.0/.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic$Id: magic_numbers,v 1.7 2004/03/05 05:04:50 marka Exp $
4da61833a1cbbca94094f9653fd970582b97a72etrawickMagic Numbers
4da61833a1cbbca94094f9653fd970582b97a72etrawickA number of data structures in the ISC and DNS libraries have an unsigned int
4da61833a1cbbca94094f9653fd970582b97a72etrawickmagic number as the first field. The purpose of the magic number is
4789804be088bcd86ae637a29cdb7fda25169521jailletcprincipally to validate that a pointer a subroutine has gotten really points
4789804be088bcd86ae637a29cdb7fda25169521jailletcto the type it claims to be. This helps detect problems caused by resources
4789804be088bcd86ae637a29cdb7fda25169521jailletcbeing freed prematurely, that have been corrupted, or that have not been
4789804be088bcd86ae637a29cdb7fda25169521jailletcproperly initialized. It can also be handy in debugging.
e50c3026198fd496f183cda4c32a202925476778covenerMagic numbers should always be the first field. They never require locking
e50c3026198fd496f183cda4c32a202925476778covenerto access. As to the actual value to be used, something mnemonic is good:
5b88c8507d5ef6d0c4cfbc78230294968175b638minfrin #define TASK_MAGIC 0x5441534BU /* TASK. */
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic #define VALID_TASK(t) ((t) != NULL && \
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic (t)->magic == TASK_MAGIC)
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic #define TASK_MANAGER_MAGIC 0x54534B4DU /* TSKM. */
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic #define VALID_MANAGER(m) ((m) != NULL && \
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic (m)->magic ==
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic TASK_MANAGER_MAGIC)
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavicUnless the memory cost is critical, most objects should have a magic number.
69301145375a889e7e37caf7cc7321ac0f91801erpluemThe magic number should be the last field set in a creation routine, so that
69301145375a889e7e37caf7cc7321ac0f91801erplueman object will never be stamped with a magic number unless it is valid.
506bfe33206b2fece40ef25f695af39dd4130facjkaluzaThe magic number should be set to zero immediately before the object is
d58a848a016d401b965111e50ef829e1641f7834minfrinMagic values are generally private to the implementation of the type. I.e.
d58a848a016d401b965111e50ef829e1641f7834minfrinthey are defined in the .c file, not the .h file.
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sfValidation of magic numbers is done by routines that manipulate the type,
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sfnot by users of the type. Indeed, user validation is usually not possible
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sfbecause the magic number is not public.
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavicMagic number checking may become a build option in a future release. E.g.
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic struct foo {
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic ISC_MAGIC_DECLARATION
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic foo_create() {
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic ISC_MAGIC_SET(value);
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic foo_destroy() {
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener ISC_MAGIC_CLEAR(value);
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener #define FOO_MAGIC 0x00010203U
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener #define VALID_FOO(f) ISC_MAGIC_VALIDATE(f, FOO_MAGIC)
44ff304057225e944e220e981d434a046d14cf06covener foo_dosomething(foo *f) {
44ff304057225e944e220e981d434a046d14cf06covener REQUIRE(VALID_FOO(f));