home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d2xx / d240 / memlib / memlib.doc < prev    next >
Text File  |  1989-08-28  |  13KB  |  302 lines
  1. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
  2. * |_o_o|\\ Copyright (c) 1989 The Software Distillery.                    *
  3. * |. o.| ||          All Rights Reserved                                  *
  4. * | .  | ||          Written by John Toebes and Doug Walker               *
  5. * | o  | ||          The Software Distillery                              *
  6. * |  . |//           235 Trillingham Lane                                 *
  7. * ======             Cary, NC 27513                                       *
  8. *                    BBS:(919)-471-6436                                   *
  9. \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  10.  
  11. This material is Copyright (C) 1988 and 1989 The Software Distillery.
  12. It may be distributed freely as long as the following restrictions are met:
  13.  
  14.    1.  All files present in the distribution package must be redistributed
  15.        with the package, including this documentation file.  If you 
  16.        distribute on diskette, all files must be on a single diskette.
  17.  
  18.    2.  The distributor may charge a fee to recover distribution costs.
  19.        The fee for diskette distribution should not be more than the cost 
  20.        to obtain the same diskette from Fred Fish or The Software Distillery,
  21.        whichever is greater.  Current charge from The Software Distillery
  22.        is $6 per disk, including all postage and handling charges.
  23.  
  24.    3.  The distributor agrees to cease distributing the programs and data
  25.        involved if requested to do so by authors or any member of The 
  26.        Software Distillery.
  27.  
  28. ------------------------------DISCLAIMER
  29.  
  30. Neither The Software Distillery nor any of its members will be liable for 
  31. any damage arising from the failure of this program to perform as described,
  32. or any destruction of other programs or data residing on a system 
  33. attempting to run the program.  While we know of no damaging errors, the 
  34. user of this program uses it at his or her own risk.
  35.  
  36. ============================================================================
  37.  
  38. Welcome to the MemWatch Library!  You may be familiar with MemWatch I
  39. and II.  The MemWatch library adds lots of memory debugging features
  40. that you link into your program.  MemWatch III, under development now,
  41. will communicate with these routines to provide asynchronous memory
  42. checking - that is, the external MemWatch III process will tell you if
  43. your program abuses its own memory.  
  44.  
  45. The MemWatch library compiles under Lattice C 5.02 and may work under 
  46. previous versions.  Lattice users can link with the provided library;
  47. if the memory features are turned off, no additional code will be linked 
  48. in.  Manx users may link the routines in with their code by linking in 
  49. the .o files 'mwcontrol.o', 'mwalcfre.o' and 'mwreport.o', but they will 
  50. have to remove these .o files if they remove the memory debugging 
  51. features.  I have not tried to compile this code with Manx, but I know of
  52. no reason why it wouldn't work.
  53.  
  54. The program-level memory debug routines are controlled by a 
  55. preprocessor symbol, MWDEBUG, and are #defined to nothing if the 
  56. symbol is not defined.  To link the program-level routines into 
  57. your code, do the following:
  58.  
  59. 1. Include the file "memwatch.h" into each file that will be
  60.    allocating or freeing memory.   (Don't include "mempriv.h" - it is
  61.    for the internal use of the memwatch.lib routines only).
  62.  
  63. 2. #define the symbol MWDEBUG at some point before memwatch.h is
  64.    included.  This could be in another include file, or in the
  65.    program file.  If the symbol MWDEBUG is not defined, all the
  66.    MemWatch routines disappear, thus adding nothing to your code
  67.    size.
  68.  
  69. 3. Insert a call to the function MWInit in your main() program 
  70.    before any memory calls.
  71.  
  72. 4. Insert a call to MWTerm in your main() program just before
  73.    it exits.  If you use exit() to exit from multiple places,
  74.    try
  75.  
  76.    #define EXIT(rc) {MWTerm(); exit(rc);}
  77.  
  78.    and replace all occurrences of exit with EXIT.
  79.  
  80. The program-level MemWatch interface is described below.
  81.  
  82. ---------------------------------------------------------------------
  83.  
  84.    void MWInit(FILE *debugfile, LONG flags);
  85.  
  86.    Call this routine exactly once, before any other memory allocation
  87.    calls.
  88.  
  89.    The debugfile is a file opened with the fopen() function to be
  90.    used for all debugging messages.  If debugfile is NULL, stdout
  91.    will be used.  If the MWF_NOLOG flag is on (see below), no
  92.    debugging file will be used.
  93.  
  94.    The flags can be one or more of the following, ORed together if 
  95.    necessary:
  96.  
  97.    MWF_EXT:     If set, attempt to communicate with the external MemWatch 
  98.                 process.  The external process under development, so don't
  99.                 set this flag until it is available or you will get
  100.                 warning messages.
  101.  
  102.    MWF_NOLOG:   If set, do not print error or warning messages.
  103.  
  104.    MWF_NOCHECK: If set, do not check all allocated memory each time
  105.                 a memory routine is called.  If not set, every
  106.                 AllocMem, FreeMem, malloc or free call will cause all 
  107.                 allocated memory to be examined.  This can be slow, but
  108.                 it's safe.
  109.  
  110.    MWF_NOFREE:  If set, do not free memory left allocated when the
  111.                 program exits.  If not set, any memory you allocated
  112.                 and did not free will be freed on your behalf.
  113.  
  114.    MWF_NOFTRASH: If set, freed memory will not be trashed.  This does
  115.                 save some time, but it is valuable to trash freed memory
  116.                 to verify you aren't still using it.
  117.  
  118.    MWF_NOFKEEP: If set, free memory immediately when FreeMem or free is
  119.                 called.  If not set, 'freed' memory will actually be kept
  120.                 on a chain and checked periodically for a change in its
  121.                 value.  If the value changes, you have written to freed
  122.                 memory.  MWF_NOFTRASH implies MWF_NOKEEP, since there is
  123.                 no point in keeping memory that you don't know the value 
  124.                 of.  If this flag is NOT set, kept memory will be freed 
  125.                 if the machine actually runs out of memory.
  126.  
  127.    MWF_NOATRASH: If set, memory will not be trashed upon allocation.  This
  128.                 also saves some time, but it is extremely valuable to trash
  129.                 allocated memory to be sure you aren't relying on side
  130.                 effects for your program to run correctly.
  131.  
  132.  
  133. ---------------------------------------------------------------------
  134.  
  135.    void MWTerm(void);
  136.  
  137.    Call this routine exactly once, after all memory functions have
  138.    been completed.  It will always generate a check, even if MWF_NOCHECK
  139.    has been set.
  140.  
  141. ---------------------------------------------------------------------
  142.  
  143.    char *MWAllocMem(LONG size, LONG flags, char *file, int line);
  144.    void *MWmalloc(unsigned n, char *file, int line);
  145.  
  146.    You should not call these routine directly, but your AllocMem
  147.    and malloc calls will be defined to call them if the symbol MWDEBUG 
  148.    is defined.  
  149.  
  150.    !!!NOTE: MWmalloc is not a complete substitute for the malloc() 
  151.    function!!!!  In particular, malloc allows you to access the last 
  152.    piece of malloc'ed memory freed;  MWmalloc does NOT allow this!!   
  153.    I stuck this in 'cause it was easy;  if it breaks your program, either 
  154.    remove the #define, implement MWmalloc correctly, or complain to me.  
  155.    realloc() is NOT SUPPORTED.
  156.  
  157. ---------------------------------------------------------------------
  158.  
  159.    void MWFreeMem(char *ptr, LONG size);
  160.    int MWfree(void *b);
  161.  
  162.    You should not call these routine directly, but your FreeMem
  163.    calls will be defined to call them if the symbol MWDEBUG is defined.
  164.  
  165. ---------------------------------------------------------------------
  166.  
  167.    void MWReport(FILE *reportfile, char *title, int level);
  168.  
  169.    Call this routine any time you want a report on how much memory
  170.    you are using.  The 'reportfile' is a file to send the report
  171.    to.  If reportfile is NULL, the debug log file will be used.
  172.  
  173.    'title' is any character string you want.  It will be used to
  174.    label the dumped output.  Use NULL for no title.
  175.  
  176.    'level' tells how much detail you want in the report.  It is one
  177.    of the following values:
  178.  
  179.    MWR_NONE - Don't print anything.
  180.    MWR_SUM  - Print current and total memory usage
  181.    MWR_FULL - Print a short description of each outstanding allocation
  182.  
  183. ---------------------------------------------------------------------
  184.  
  185.    void MWCheck(void);
  186.  
  187.    Call this routine when you want to verify all your allocations are
  188.    clean.  If you haven't set the MWF_NOCHECK flag, all allocations
  189.    are checked every time you do an Alloc or Free operation anyway,
  190.    but you might want to use this directly if you set the flag or if
  191.    you go long periods of time without allocating memory.
  192.  
  193. ---------------------------------------------------------------------
  194.  
  195.    void MWLimit(LONG chip, LONG fast);
  196.  
  197.    Call this routine if you want to set an artificial 'cap' on the
  198.    amount of memory available.  Any allocations that ask for memory
  199.    that would push your total allocation above the specified limits
  200.    will fail, even if memory is available to fill them.  Keep in mind
  201.    that this doesn't take fragmentation into account, so it doesn't
  202.    guarantee your program will work on a smaller memory machine!
  203.    You can simulate out-of-memory conditions by calling MWLimit
  204.    with (0,0) - no allocations will ever succeed until the limit
  205.    is raised above the current usage level.
  206.  
  207.    The 'chip' parameter sets a limit on chip memory;  the 'fast'
  208.    parameter sets a limit on fast memory.  If the specified limit for
  209.    a category is -1, the limit will be set at the current usage amount.
  210.    Thus, any frees you do will improve your situation.
  211.  
  212.    If you want to remove a limit, set it to some extremely large value,
  213.    like 0x7fffffff.
  214.  
  215.  
  216. ---------------------------------------------------------------------
  217.  
  218.  
  219. The enclosed program 'test' will test the memlib functions for you.
  220. Invoke it by typing 'test' from CLI.  You will get a prompt like
  221.  
  222. Enter command (h for help):
  223.  
  224. If you type 'h', it will say
  225.  
  226. Commands are:\n");
  227. A <n>     --> Allocate 'n' bytes, replace current allocation
  228. W <n>     --> Write 'n' bytes to most recent allocation
  229. F <n>     --> Free 'n' bytes starting at most recent allocation
  230. R <lvl>   --> Report on usage; <lvl> is 1 for less, 2 for more detail
  231. C         --> Check all allocations, report errors
  232. Q         --> Quit program
  233.  
  234. Basically, the 'A' command calls AllocMem;  the 'F' command calls FreeMem;
  235. the 'W' command writes zeroes to the last memory allocated with 'A', even
  236. if it has been freed in the meantime;  the 'R' command calls MWReport; and
  237. the 'C' command calls MWCheck.
  238.  
  239.  
  240. Here are some examples of running test:
  241. > 
  242. > Enter command (h for help): a 10
  243. > 10 bytes allocated, value 0x00221254
  244. > 
  245. > Enter command (h for help): w 11        <-- Wrote over the end!
  246. > 11 bytes cleared
  247. > 
  248. > Enter command (h for help): c
  249. > MemWatch ERROR: Trailer trashed
  250. > 0x00221254 length       10 allocated line    36 file test.c
  251. > Check complete
  252. > 
  253. > 
  254. > 
  255. > Enter command (h for help): q
  256. > MemWatch ERROR: The following allocations were not freed:
  257. > 0x00221254 length       10 allocated line    36 file test.c
  258.  
  259. -------------------------------------------------------------------------
  260. > 
  261. > Enter command (h for help): a 100
  262. > 100 bytes allocated, value 0x002232cc
  263. > 
  264. > Enter command (h for help): f 100
  265. > 100 bytes freed
  266. > 
  267. > Enter command (h for help): w 10        <-- Wrote to mem after free!
  268. > 10 bytes cleared
  269. > 
  270. > Enter command (h for help): c
  271. > MemWatch ERROR: Freed memory modified
  272. > 0x002232CC length      100 allocated line    36 file test.c
  273. > Check complete
  274. > 
  275. > 
  276. > 
  277. > Enter command (h for help): q
  278.  
  279. -------------------------------------------------------------------------
  280.  
  281. > Enter command (h for help): a 1000
  282. > 1000 bytes allocated, value 0x002b073c
  283. > 
  284. > Enter command (h for help): f 1000
  285. > 1000 bytes freed
  286. > 
  287. > Enter command (h for help): f 1000       <-- Freed memory twice!
  288. > Invalid FreeMem call, addr 0x002B073C length     1000
  289. > 1000 bytes freed
  290. > 
  291. > Enter command (h for help): a 10
  292. > 10 bytes allocated, value 0x00229ee4
  293. > 
  294. > Enter command (h for help): f 5          <-- Freed too few bytes!
  295. > FreeMem called with length        5 on the following allocation:
  296. > 0x00229EE4 length       10 allocated line    36 file test.c
  297. > 5 bytes freed
  298. > 
  299. > Enter command (h for help): q
  300. > MemWatch ERROR: The following allocations were not freed:
  301. > 0x00229EE4 length       10 allocated line    36 file test.c
  302.