home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / utilities / safemem2.lha / safemem.doc < prev    next >
Encoding:
Text File  |  1993-01-05  |  5.2 KB  |  162 lines
  1.  
  2.                SafeMem V2.0: A memory management safety net.
  3.                ---------------------------------------------
  4.                         written by Simon P. Bullen
  5.  
  6.     Contents
  7.     --------
  8.     In this archive, there should be the following files:
  9.  
  10.         FileName        Size
  11.         -------------------    ------
  12.         makefile        326
  13.         SafeMem.c        12960
  14.         safemem.doc        5326
  15.         SafeMem.h        1839
  16.         safemem.lib        13032
  17.         SafeMem_parallel.c    2931
  18.         SafeMem_parallel.h    277
  19.         test            9056
  20.         test.c            342
  21.         -------------------    ------
  22.         Total:            46089   
  23.  
  24.     Legal Stuff
  25.     -----------
  26.     This  software  is not public domain.  All material in this archive
  27. is  ©  Copyright Simon P.  Bullen.  The software is freely distrubtable, so
  28. long  as  no  more  than a nominal fee is charged for media.  Everything in
  29. this distrubution must be kept together, in original, unmodified form.
  30.     The  files  may be modified for your own personal use, but modified
  31. files  must  not  be distributed.  No commercial usage is permitted without
  32. written permission from the author.
  33.     The material is provided "as is" without warranty of any kind.  The
  34. author accepts no responsibilty for damages caused by this software.
  35.  
  36.     Contributions
  37.     -------------
  38.     If  you  have  any  suggestions,  remarks,  bugs or gratifications,
  39. please write to me at
  40.  
  41.     s914373@minyos.xx.rmit.OZ.AU (until the end of 1993)
  42.  
  43.     or
  44.  
  45.     Simon P. Bullen
  46.     PO BOX 12138
  47.     A'Beckett St
  48.     Melbourne 3000
  49.     Australia
  50.  
  51.  
  52.     INTRODUCTION
  53.     ------------
  54.     Ever had the problem of a program you're trying to debug swallowing
  55. 24  bytes  somewhere,  and  not  knowing  where?  Or perhaps you're playing
  56. around  with  one of the more complex memory structures, and it gurus a lot
  57. due to incorrect memory frees?  Painful to debug, aren't they?
  58.  
  59.     Well, no longer!!  With SafeMem installed, your programs will crash
  60. from memory mismanagement never again!
  61.  
  62.     SafeMem  is  a small link library that places a "safety net" around
  63. all  your  calls to AllocMem(), AllocAbs(), FreeMem(), malloc(), realloc(),
  64. calloc()  and  free().   It  traps errors such as freeing a block you never
  65. owned,  freeing  a block twice, freeing a block with an incorrect size, and
  66. never freeing a block at all.
  67.  
  68.     SafeMem  is  intended  as a development tool - use it while you are
  69. writing  & debugging your programs, then when it's finished & bug free, you
  70. recompile it again without SafeMem.
  71.  
  72.  
  73.     USAGE
  74.     -----
  75.     SafeMem   is  intended  as  a  development  tool  for  use  with  C
  76. programming, although header files could be constructed to make it function
  77. with other languages.
  78.  
  79.     To install it, simply 
  80.  
  81.     #define SAFEMEM
  82.     #include "safemem/safemem.h" /* this must be AFTER your exec protos & 
  83.                                   * pragmas  
  84.                                   */
  85.  
  86.     You  must  do  this  to every source module, otherwise you will run
  87. into  problems  when  a  non-safemem  module  frees  some  memory  that was
  88. allocated by a safemem module.  You must also link with safemem.lib.
  89.  
  90.     If  you  don't  include the #define, then the SafeMem routines will
  91. compile  away to nothing.  During your program, you may call AllocMem, etc,
  92. just  as  usual,  and  the  SafeMem  routines  will be transparently called
  93. instead.
  94.  
  95.     As well as the normal memory management routines, you get two extra
  96. functions - ShowMemList() and FreeMemList().
  97.  
  98.     ShowMemList()  displays  a list of all the memory that has not been
  99. freed  at  this  time.   (If there is no unfreed memory, ShowMemList() does
  100. nothing).
  101.  
  102.     test.c 17: Memory List
  103.         Address      Size         File             Line
  104.         -------      ----         ----             ----
  105.         $794ea68     1024         test.c           13
  106.  
  107.     FreeMemList()  frees  all  remaining memory on the memory list.  If
  108. FreeMemList() actually finds something to free, it also prints a message:
  109.  
  110.     test.c 18: Freeing Memory List
  111.  
  112.  
  113.     DISABLING SAFEMEM WITHOUT RECOMPILING EVERYTHING
  114.     ------------------------------------------------
  115.     There is a global variable, gbl_SafeMem, which provides an override
  116. for the safemem functions.  When gbl_SafeMem is 0, the safemem routines are
  117. disabled (gbl_SafeMem defaults to 1).
  118.  
  119.  
  120.     REDIRECTING THE ERRORS TO SOMETHING OTHER THAN STDOUT
  121.     -----------------------------------------------------
  122.     There  are times when printing the errors to stdout is unacceptable
  123. -  when  you  are  debugging  multiple  tasks,  for  example (Tasks are not
  124. permitted to use dos function such as Write).
  125.     All  the  SafeMem  output  is  funnelled  through a function called
  126. gbl_SafeMemOutput,  which is actually a pointer to a function, so it can be
  127. reassigned.
  128.     To  redirect  the  output  through  a different function, merely do
  129. something like this:
  130.  
  131.     void ExampleOutputFunction(char *Text)
  132.     {
  133.       fprintf(stderr, Text);
  134.     }
  135.     
  136.     main()
  137.     {
  138.       gbl_SafeMemOutput = ExampleOutputFunction;
  139.       ..
  140.     }
  141.  
  142.     Provided  in  this library is a set of functions that will redirect
  143. the  output to the parallel port.  To use them, all you need do is (as well
  144. as  the  normal procedure):
  145.  
  146.     #include "safemem_parallel.h"
  147.     
  148.     main()
  149.     {
  150.       OpenSafeMemParallel(); /* You should probably check the return
  151.                               * code of this function to make sure
  152.                               * it opened ok 
  153.                               */
  154.     ..
  155.     
  156.     ..
  157.       CloseSafeMemParallel();
  158.     }
  159.  
  160.     The  parallel  port  routines  could  easily  be adapted to use the
  161. serial port instead.
  162.