home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / code / stubshack / StubsHack / !Help next >
Encoding:
Text File  |  1995-01-07  |  4.3 KB  |  139 lines
  1. StubsHack version 1.10 07 Jan 1995
  2. ----------------------------------
  3.  
  4.  
  5.  
  6.  
  7.  
  8. Introduction
  9. ------------
  10.  
  11. This is a C library which uses an idea of Martin Ebourne's to enable you
  12. to very easily redirect all calls to the ANSI memory allocation
  13. functions (malloc, realloc, calloc, free) to your own function. This
  14. could be used to add heap-checking to the malloc functions.
  15.  
  16. The important point is that this happens at *runtime*, so even if you
  17. link your program with a library which was compiled years ago, all
  18. malloc calls within the library will be redirected.
  19.  
  20. See my 'HeapGraph' library for an example of how to use StubsHack, or
  21. the project inside the 'Example' directory for an example of how to
  22. redirect individual shared-c-library functions.
  23.  
  24.  
  25.  
  26.  
  27. Installation
  28. ------------
  29.  
  30. You should move the StubsHack directory into your C path. Don't move any
  31. headers into an existing .h. directory, as they are refered to as
  32. 'StubsHack.<headername>.h' in the source.
  33.  
  34. I find this to be a much simpler way of organising C libraries than
  35. changing C$Path etc. It also protects against problems when header files
  36. from different libraries have the same name.
  37.  
  38. The actual library is 'C:StubsHack.o.SHLib'.
  39.  
  40.  
  41.  
  42.  
  43. How StubHack works  
  44. ------------------
  45.  
  46. When a program is linked with the object file Stubs, all calls to the
  47. standard C functions like printf, malloc etc. are made (by the linker)
  48. to branch (usually with link) to an address within Stubs. 
  49.  
  50. The instruction at this address isn't the start of the function,
  51. however. It is just a branch to the malloc/etc function inside the
  52. SharedCLib module. 
  53.  
  54. This branch is set to point to the right place within the SharedCLib
  55. module when the program is run, before the main() function is started.
  56. In this way, the SharedCLibrary is used by many different applications
  57. at the same time.
  58.  
  59. StubsHack simply changes the branch instruction in stubs to be a branch
  60. to a different function. All users of ANSI C functions continue to call
  61. this instruction, so they all end up going to the new function.
  62.  
  63.  
  64.  
  65. What you can do with StubsHack 
  66. ------------------------------
  67.  
  68. As well as providing low-level functions to read/change the destination
  69. of any stubs branch instruction, StubsHack provides a general functions
  70. which should be used to intercept/take over the four ANSI C allocation
  71. functions malloc, realloc, calloc and free, and a function for
  72. redirecting individual stubs functions.
  73.  
  74. It provides two things:
  75.  
  76. 1) A way of changing the contents of the stubs branch instructions for
  77.    malloc/realloc/callos/free, so that it points to one of your
  78.    functions.
  79.  
  80. 2) The address (normally within the sharedClibrary) of the original
  81.    malloc/realloc/calloc/free function.
  82.  
  83. The second enables you to make a 'wrapper' function for the ANSI
  84. re/m/calloc/free functions - eg. you redirect all malloc calls to your
  85. own MallocWrap function, and within MallocWrap, you use the actual
  86. shared C lib function pointers to call the original SharedCLib function.
  87.  
  88. This could be used, for eg., to add heap-verification to your program,
  89. by storing special info in each malloc block, and checking this info is
  90. ok when freeing the block. 
  91.  
  92. For example, the Mnemosyne library does just this to provide
  93. heap-checking and limited protection against overwriting memory etc by
  94. having wrapping functions for malloc/realloc/calloc/free, but only by
  95. #define-ing malloc to mnem_malloc etc, so you have to recompile all
  96. files and libraries used in the program to get the checking. 
  97.  
  98. Obviously, recompiling your source is easy, but recompiling DeskLib (for
  99. eg.) is not a trivial matter.
  100.  
  101. With StubsHack, it would be easy to make something like Mnemosyne which
  102. would check all memory allocations without needing recompilation of all
  103. libraries etc. In fact, this has been done, and will hopefully be
  104. included with Mnemosyne when it is released.
  105.  
  106.  
  107.  
  108.  
  109.  
  110. Other
  111. -----
  112.  
  113. All the contents of the StubsHack directory are © Julian Smith, 1994.
  114. Feel free to distribute it, but only distribute the original version. If
  115. you make any changes, please send them to me and I'll send them out with
  116. the next release.
  117.  
  118. Any suggestions/comments/bug fixes etc are very much welcomed.
  119.  
  120.  
  121.  
  122. - Julian Smith
  123.  
  124.  
  125. ------------------------
  126. julians@cogsci.ed.ac.uk
  127. ------------------------
  128.  
  129. or:
  130.  
  131. ------------------------
  132. Department of Psychology
  133. University of Edinburgh
  134. 7 George Square
  135. Edinburgh
  136. EH8 9JZ
  137. UK
  138. ------------------------
  139.