memwatch.h

MiniWinOuterSM MiniWinOuterSM

**      is legal in ANSI C, therefore a warning is written to the log file,
**      but the error counter remains the same. This is legal using C++,
**      so the warning does not appear with delete.
**      Detect: When you free(NULL).
**      Action: The free() is cancelled.
**  Failed:
**      A request to allocate memory failed. If the allocation is
**      small, this may be due to memory depletion, but is more likely
**      to be memory fragmentation problems. The amount of memory
**      allocated so far is displayed also.
**      Detect: When you new, malloc(), realloc() or calloc() memory.
**      Action: NULL is returned.
**  Realloc:
**      A request to re-allocate a memory buffer failed for reasons
**      other than out-of-memory. The specific reason is shown.
**      Detect: When you realloc()
**      Action: realloc() is cancelled, NULL is returned
**  Limit fail:
**      A request to allocate memory failed since it would violate
**      the limit set using mwLimit(). mwLimit() is used to stress-test
**      your code under simulated low memory conditions.
**      Detect: At new, malloc(), realloc() or calloc().
**      Action: NULL is returned.
**  Assert trap:
**      An ASSERT() failed. The ASSERT() macro works like C's assert()
**      macro/function, except that it's interactive. See your C manual.
**      Detect: On the ASSERT().
**      Action: Program ends with an advisory message to stderr, OR
**              Program writes the ASSERT to the log and continues, OR
**              Program asks Abort/Retry/Ignore? and takes that action.
**  Verify trap:
**      A VERIFY() failed. The VERIFY() macro works like ASSERT(),
**      but if MEMWATCH is not defined, it still evaluates the
**      expression, but it does not act upon the result.
**      Detect: On the VERIFY().
**      Action: Program ends with an advisory message to stderr, OR
**              Program writes the VERIFY to the log and continues, OR
**              Program asks Abort/Retry/Ignore? and takes that action.
**  Wild pointer:
**      A no-mans-land buffer has been written into. MEMWATCH can
**      allocate and distribute chunks of memory solely for the
**      purpose of trying to catch random writes into memory.
**      Detect: Always on CHECK(), but can be detected in several places.
**      Action: The error is logged, and if an ARI handler is installed,
**              it is executed, otherwise, execution continues.
**  Unfreed:
**      A memory buffer you allocated has not been freed.
**      You are informed where it was allocated, and whether any
**      over or underflow has occured. MemWatch also displays up to
**      16 bytes of the data, as much as it can, in hex and text.
**      Detect: When MemWatch terminates.
**      Action: The buffer is freed.
**  Check:
**      An error was detected during a CHECK() operation.
**      The associated pointer is displayed along with
**      the file and line where the CHECK() was executed.
**      Followed immediately by a normal error message.
**      Detect: When you CHECK()
**      Action: Depends on the error
**  Relink:
**      After a MEMWATCH internal control block has been trashed,
**      MEMWATCH tries to repair the damage. If successful, program
**      execution will continue instead of aborting. Some information
**      about the block may be gone permanently, though.
**      Detect: N/A
**      Action: Relink successful: program continues.
**              Relink fails: program aborts.
**  Internal:
**      An internal error is flagged by MEMWATCH when it's control
**      structures have been damaged. You are likely using an uninitialized
**      pointer somewhere in your program, or are zapping memory all over.
**      The message may give you additional diagnostic information.
**      If possible, MEMWATCH will recover and continue execution.
**      Detect: Various actions.
**      Action: Whatever is needed
**  Mark:
**      The program terminated without umarking all marked pointers. Marking
**      can be used to track resources other than memory. mwMark(pointer,text,...)
**      when the resource is allocated, and mwUnmark(pointer) when it's freed.
**      The 'text' is displayed for still marked pointers when the program
**      ends.
**      Detect: When MemWatch terminates.
**      Action: The error is logged.
**
**
************************************************************************
**
**  The author may be reached by e-mail at the address below. If you
**  mail me about source code changes in MEMWATCH, remember to include
**  MW's version number.
**
**      Johan Lindh
**      [e-mail]
**
** The latest version of MEMWATCH may be downloaded from
** http://www.linkdata.se/
*/
#define MEMWATCH

#ifndef __MEMWATCH_H
#define __MEMWATCH_H

/* Make sure that malloc(), realloc(), calloc() and free() are declared. */
/*lint -save -e537 */
#include <stdlib.h>
/*lint -restore */

#ifdef __cplusplus
extern "C" {
#endif


/*
** Constants used
**  All MEMWATCH constants start with the prefix MW_, followed by
**  a short mnemonic which indicates where the constant is used,
**  followed by a descriptive text about it.
*/

#define MW_ARI_NULLREAD 0x10    /* Null read (to start debugger) */
#define MW_ARI_ABORT    0x04    /* ARI handler says: abort program! */
#define MW_ARI_RETRY    0x02    /* ARI handler says: retry action! */
#define MW_ARI_IGNORE   0x01    /* ARI handler says: ignore error! */

#define MW_VAL_NEW      0xFE    /* value in newly allocated memory */
#define MW_VAL_DEL      0xFD    /* value in newly deleted memory */
#define MW_VAL_NML      0xFC    /* value in no-mans-land */
#define MW_VAL_GRB      0xFB    /* value in grabbed memory */

#define MW_TEST_ALL     0xFFFF  /* perform all tests */
#define MW_TEST_CHAIN   0x0001  /* walk the heap chain */
#define MW_TEST_ALLOC   0x0002  /* test allocations & NML guards */
#define MW_TEST_NML     0x0004  /* test all-NML areas for modifications */

#define MW_NML_NONE     0       /* no NML */
#define MW_NML_FREE     1       /* turn FREE'd memory into NML */
#define MW_NML_ALL      2       /* all unused memory is NML */
#define MW_NML_DEFAULT  0       /* the default NML setting */

#define MW_STAT_GLOBAL  0       /* only global statistics collected */
#define MW_STAT_MODULE  1       /* collect statistics on a module basis */
#define MW_STAT_LINE    2       /* collect statistics on a line basis */
#define MW_STAT_DEFAULT 0       /* the default statistics setting */

/*
** MemWatch internal constants
**  You may change these and recompile MemWatch to change the limits
**  of some parameters. Respect the recommended minimums!
*/
#define MW_TRACE_BUFFER 2048    /* (min 160) size of TRACE()'s output buffer */
#define MW_FREE_LIST    64      /* (min 4) number of free()'s to track */

/*
** Exported variables
**  In case you have to remove the 'const' keyword because your compiler
**  doesn't support it, be aware that changing the values may cause
**  unpredictable behaviour.
**  - mwCounter contains the current action count. You can use this to
**      place breakpoints using a debugger, if you want.
*/
#ifndef __MEMWATCH_C
extern const unsigned long mwCounter;
#endif

/*
** System functions
**  Normally, it is not nessecary to call any of these. MEMWATCH will
**  automatically initialize itself on the first MEMWATCH function call,
**  and set up a call to mwAbort() using atexit(). Some C++ implementations
**  run the atexit() chain before the program has terminated, so you
**  may have to use mwInit() or the MemWatch C++ class to get good
**  behaviour.
**  - mwInit() can be called to disable the atexit() usage. If mwInit()
**      is called directly, you must call mwTerm() to end MemWatch, or
**      mwAbort().
**  - mwTerm() is usually not nessecary to call; but if called, it will
**      call mwAbort() if it finds that it is cancelling the 'topmost'
**      mwInit() call.
**  - mwAbort() cleans up after MEMWATCH, reports unfreed buffers, etc.
*/
void  mwInit( void );
void  mwTerm( void );
void  mwAbort( void );

/*
** Setup functions
**  These functions control the operation of MEMWATCH's protective features.
**  - mwFlushNow() causes MEMWATCH to flush it's buffers.
**  - mwDoFlush() controls whether MEMWATCH flushes the disk buffers after
**      writes. The default is smart flushing: MEMWATCH will not flush buffers
**      explicitly until memory errors are detected. Then, all writes are
**      flushed until program end or mwDoFlush(0) is called.
**  - mwLimit() sets the allocation limit, an arbitrary limit on how much
**      memory your program may allocate in bytes. Used to stress-test app.
**      Also, in virtual-memory or multitasking environs, puts a limit on
**      how much MW_NML_ALL can eat up.
**  - mwGrab() grabs up X kilobytes of memory. Allocates actual memory,
**      can be used to stress test app & OS both.
**  - mwDrop() drops X kilobytes of grabbed memory.
**  - mwNoMansLand() sets the behaviour of the NML logic. See the
**      MW_NML_xxx for more information. The default is MW_NML_DEFAULT.
**  - mwStatistics() sets the behaviour of the statistics collector. See
**      the MW_STAT_xxx defines for more information. Default MW_STAT_DEFAULT.
**  - mwFreeBufferInfo() enables or disables the tagging of free'd buffers
**      with freeing information. This information is written in text form,
**      using sprintf(), so it's pretty slow. Disabled by default.
**  - mwAutoCheck() performs a CHECK() operation whenever a MemWatch function
**      is used. Slows down performance, of course.
**  - mwCalcCheck() calculates checksums for all data buffers. Slow!
**  - mwDumpCheck() logs buffers where stored & calc'd checksums differ. Slow!!
**  - mwMark() sets a generic marker. Returns the pointer given.
**  - mwUnmark() removes a generic marker. If, at the end of execution, some
**      markers are still in existence, these will be reported as leakage.
**      returns the pointer given.
*/
void        mwFlushNow( void );
void        mwDoFlush( int onoff );
void        mwLimit( long bytes );
unsigned    mwGrab( unsigned kilobytes );
unsigned    mwDrop( unsigned kilobytes );
void        mwNoMansLand( int mw_nml_level );
void        mwStatistics( int level );
void        mwFreeBufferInfo( int onoff );
void        mwAutoCheck( int onoff );
void        mwCalcCheck( void );
void        mwDumpCheck( void );
void *      mwMark( void *p, const char *description, const char *file, unsigned line );
void *      mwUnmark( void *p, const char *file, unsigned line );