home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dmake40.zip / dbug / malloc / _readme < prev    next >
Encoding:
Text File  |  1994-10-23  |  4.9 KB  |  134 lines
  1. # (c) Copyright 1990 Conor P. Cahill. (uunet!virtech!cpcahil) 
  2.  
  3. # You may copy, distribute, and use this software as long as this
  4.  
  5. # copyright statement is not removed.
  6.  
  7.  
  8.  
  9. This package is a collection of routines which are a drop-in replacement
  10.  
  11. for the malloc(3), memory(3), string(3), and bstring(3) library functions.
  12.  
  13.  
  14.  
  15. The purpose of these programs is to aid the development and/or debugging
  16.  
  17. of programs using these functions by providing a high level of consistancy
  18.  
  19. checking whenever a malloc pointer is used.  Due to this increased 
  20.  
  21. level of consistancy checking, these functions have a considerably larger
  22.  
  23. overhead than the standard functions, but the extra checking should be
  24.  
  25. well worth it in a development environment.
  26.  
  27.  
  28.  
  29. To use these functions all you need to do is compile the library and
  30.  
  31. include it on your loader command line.  You do not need to recompile
  32.  
  33. your code, only a relink is necessary.  
  34.  
  35.  
  36.  
  37. Features of this library:
  38.  
  39.  
  40.  
  41.  1. The malloced area returned from each call to malloc is filled with
  42.  
  43.     non-null bytes.  This should catch any use of uninitialized malloc
  44.  
  45.     area.  The fill pattern for malloced area is 0x01.
  46.  
  47.  
  48.  
  49.  2. When free is called numerous validity checks are made on the 
  50.  
  51.     pointer it is passed.  In addition, the data in the malloc block
  52.  
  53.     beyound the size requested on the initial malloc is checked to 
  54.  
  55.     verify that it is still filled with the original fill characters.
  56.  
  57.  
  58.  
  59.     This is usefull for catching things like:
  60.  
  61.  
  62.  
  63.         ptr = malloc(5);
  64.  
  65.         ptr[5] = '\0';
  66.  
  67.  
  68.  
  69.         /*
  70.  
  71.          * You should not that this will be caught when it is
  72.  
  73.          * freed not when it is done
  74.  
  75.          */
  76.  
  77.  
  78.  
  79.     And finally, the freed block is filled with a different fill pattern
  80.  
  81.     so that you can easily determine if you are still using free'd space.
  82.  
  83.     The fill pattern for free'd areas is 0x02.
  84.  
  85.  
  86.  
  87.     This is usefull for catching things like:
  88.  
  89.  
  90.  
  91.         ptr = malloc(20);
  92.  
  93.  
  94.  
  95.         bptr = ptr+10;
  96.  
  97.  
  98.  
  99.         /* do something usefule with bptr */
  100.  
  101.  
  102.  
  103.         free(ptr);
  104.  
  105.  
  106.  
  107.         /* 
  108.  
  109.          * now try to do something useful with bptr, it should
  110.  
  111.          * be trashed enough that it would cause real problems
  112.  
  113.          * and when you went to debug the problem it would be
  114.  
  115.          * filled with 0x02's and you would then know to look 
  116.  
  117.          * for something free'ing what bptr points to.
  118.  
  119.          */
  120.  
  121.         
  122.  
  123.  
  124.  
  125.  3. Whenever a bstring(3)/string(3)/memory(3) function is called, it's 
  126.  
  127.     parameters are checked as follows:
  128.  
  129.  
  130.  
  131.     If they point somewhere in the malloc arena
  132.  
  133.         If the operation goes beyond requested malloc space
  134.  
  135.             call malloc_warning()
  136.  
  137.  
  138.  
  139.     This is usefull for catching things like:
  140.  
  141.  
  142.  
  143.         ptr = malloc(5);
  144.  
  145.         strcpy(ptr,"abcde");
  146.  
  147.             
  148.  
  149.     
  150.  
  151.  4. Malloc_warning() and malloc_fatal() are used when an error condition
  152.  
  153.     is detected.  If the error is severe, malloc_fatal is called.  
  154.  
  155.     Malloc_warning is used otherwise.  The decision about what is fatal
  156.  
  157.     and what is a warning was made somewhat arbitrarily.
  158.  
  159.  
  160.  
  161.     Warning messages include:
  162.  
  163.  
  164.  
  165.     Calling free with a bad pointer
  166.  
  167.         Calling a bstring/string/memory (3) function which will go beyond
  168.  
  169.         the end of a malloc block (Note that the library function is
  170.  
  171.             not modified to refuse the operation.  If malloc warnings are
  172.  
  173.         in the default IGNORE case, the operation will continue and 
  174.  
  175.         at some point cause a real problem).
  176.  
  177.  
  178.  
  179.     Fatal errors are:
  180.  
  181.  
  182.  
  183.     Detectable corruption to the malloc chain.
  184.  
  185.     
  186.  
  187.  
  188.  
  189.  5. The operations to perform when an error is detected are specified at
  190.  
  191.     run time by the use of environment variables.
  192.  
  193.  
  194.  
  195.     MALLOC_WARN - specifies the warning error message handling
  196.  
  197.     MALLOC_FATAL - specifies the fatal error handling
  198.  
  199.  
  200.  
  201.  
  202.  
  203.     When one of these error conditions occur you will get an error
  204.  
  205.     message and the handler will execute based upon what setting
  206.  
  207.     is in the environment variables.  Currently understood settings
  208.  
  209.     are as follows:
  210.  
  211.  
  212.  
  213.           0 - continue operations
  214.  
  215.           1 - drop core and exit
  216.  
  217.           2 - just exit
  218.  
  219.           3 - drop core, but continue executing.  Core files will
  220.  
  221.              be placed into core.[PID].[counter] i.e: core.00123.001
  222.  
  223.         128 - dump malloc chain and continue
  224.  
  225.         129 - dump malloc chain, dump core, and exit
  226.  
  227.         130 - dump malloc chain, exit
  228.  
  229.         131 - dump malloc chain, dump core, continue processing
  230.  
  231.         
  232.  
  233.  
  234.  
  235.     There is an additional environment variable MALLOC_ERRFILE which
  236.  
  237.     is used to indicate the name of the file for error message output.
  238.  
  239.  
  240.  
  241.     For example, to set up the session to generate a core file for
  242.  
  243.     every malloc warning, to drop core and exit on a malloc fatal, and 
  244.  
  245.     to log all messages to the file "malloc_log" do the following:
  246.  
  247.  
  248.  
  249.         MALLOC_WARN=131
  250.  
  251.         MALLOC_FATAL=1
  252.  
  253.         MALLOC_ERRFILE=malloc_log
  254.  
  255.  
  256.  
  257.         export MALLOC_WARN MALLOC_FATAL MALLOC_ERRFILE
  258.  
  259.  
  260.  
  261.  6. The function malloc_dump() is available to dump the malloc chain whenever
  262.  
  263.     you might want.  It's only argument is a file descriptor to use to write
  264.  
  265.     the data.  Review the code if you need to know what data is printed.
  266.  
  267.