watchmalloc(3MALLOC)					Memory Allocation Library Functions				      watchmalloc(3MALLOC)

NAME

       watchmalloc, cfree, memalign, valloc - debugging memory allocator

SYNOPSIS

       #include <stdlib.h>

       void *malloc(size_t size);

       void free(void *ptr);

       void *realloc(void *ptr, size_t size);

       void *memalign(size_t alignment, size_t size);

       void *valloc(size_t size);

       void *calloc(size_t nelem, size_t elsize);

       void cfree(void *ptr, size_t nelem, size_t elsize);

       #include <malloc.h>

       int mallopt(int cmd, int value);

       struct mallinfo mallinfo(void);

DESCRIPTION

       The  collection of malloc() functions in this shared object are an optional replacement for the standard versions of the same  functions in
       the system C library. See malloc(3C). They provide a more strict interface than the standard versions and enable enforcement of the  inter-
       face through the watchpoint facility of /proc. See proc(4).

       Any dynamically linked application can be run with these functions in place of the standard functions if the following string is present in
       the environment (see ld.so.1(1)):

	LD_PRELOAD=watchmalloc.so.1

       The individual function interfaces are identical to the standard ones as described in malloc(3C). However, laxities provided in	the  stan-
       dard versions are not permitted when the watchpoint facility is enabled (see WATCHPOINTS  below):

	 o  Memory may not be freed more than once.

	 o  A pointer to freed memory may not be used in a call to realloc().

	 o  A call to malloc() immediately following a call to free() will not return the same space.

	 o  Any reference to memory that has been freed yields undefined results.

       To  enforce these restrictions partially, without great loss in speed as compared to the watchpoint facility described below, a freed block
       of memory is overwritten with the pattern 0xdeadbeef before returning from free(). The malloc() function returns with the allocated  memory
       filled  with  the  pattern 0xbaddcafe as a precaution against applications incorrectly expecting to receive back unmodified memory from the
       last free(). The calloc() function always returns with the memory zero-filled.

       Entry points for mallopt() and mallinfo() are provided as empty routines, and are present only because some malloc()  implementations  pro-
       vide them.

WATCHPOINTS

       The watchpoint facility of /proc can be applied by a process to itself. The functions in watchmalloc.so.1 use this feature if the following
       string is present in the environment:

       MALLOC_DEBUG=WATCH

       This causes every block of freed memory to be covered with WA_WRITE watched areas. If the application attempts to write any part  of  freed
       memory, it will trigger a watchpoint trap, resulting in a SIGTRAP signal, which normally produces an  application core dump.

       A  header  is  maintained  before  each block of allocated memory. Each header is covered with a watched area, thereby providing a red zone
       before and after each block of allocated memory (the header for the subsequent memory block serves as the trailing red zone for its preced-
       ing memory block). Writing just before or just after a memory block returned by malloc() will trigger a watchpoint trap.

       Watchpoints  incur  a  large  performance  penalty.  Requesting MALLOC_DEBUG=WATCH can cause the application to run 10 to 100 times slower,
       depending on the use made of allocated memory.

       Further options are enabled by specifying a comma-separated string of options:

       MALLOC_DEBUG=WATCH,RW,STOP

       WATCH	       Enables WA_WRITE watched areas as described above.

       RW	       Enables both WA_READ and WA_WRITE watched areas. An attempt either to read or write freed memory  or  the  red  zones  will
		       trigger a watchpoint trap. This incurs even more overhead and can cause the application to run up to 1000 times slower.

       STOP	       The  process  will  stop showing a FLTWATCH machine fault if it triggers a watchpoint trap, rather than dumping core with a
		       SIGTRAP signal. This allows a debugger to be attached to the live process at the point where it	underwent  the	watchpoint
		       trap. Also, the various /proc tools described in proc(1) can be used to examine the stopped process.

       One  of	WATCH  or RW must be specified, else the watchpoint facility is not engaged. RW overrides WATCH. Unrecognized options are silently
       ignored.

LIMITATIONS

       Sizes of memory blocks allocated by malloc() are rounded up to the worst-case alignment size, 8 bytes for 32-bit processes and 16 bytes for
       64-bit  processes. Accessing the extra space allocated for a memory block is technically a memory violation but is in fact innocuous.  Such
       accesses are not detected by the watchpoint facility of watchmalloc.

       Interposition of watchmalloc.so.1 fails innocuously if the target application is statically linked with respect to its malloc() functions.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       proc(1), bsdmalloc(3MALLOC), calloc(3C), free(3C), malloc(3C), malloc(3MALLOC), mapmalloc(3MALLOC), memalign(3C), realloc(3C), valloc(3C),
       libmapmalloc(3LIB), proc(4), attributes(5)

SunOS 5.10							    25 Apr 2001 					      watchmalloc(3MALLOC)