memalign(3X)

NAME | SYNOPSIS | DESCRIPTION | WATCHPOINTS | LIMITATIONS | FILES | ATTRIBUTES | SEE ALSO

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() routines in this shared object are an optional replacement for the standard versions of the same routines in the system C library. See malloc(3C). They provide a more strict interface than the standard versions and enable enforcement of the interface via the watchpoint facility of /proc. See proc(4).

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

---

 LD_PRELOAD=watchmalloc.so.1

---

The individual routine interfaces are identical to the standard ones as described in malloc(3C). However, laxities provided in the standard versions are not permitted:

• Memory may not be freed more than once.

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

• A malloc() immediately following a free() will not return the same space.

• 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(). malloc() returns with the allocated memory filled with the pattern 0xbaddcafe as a precaution against programs incorrectly expecting to receive back unmodified memory from the last free(). (calloc() 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 provide them.

WATCHPOINTS

The watchpoint facility of /proc can be applied by a process to itself. The routines 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 program attempts to write any part of freed memory, it will trigger a watchpoint trap, which will result in a SIGTRAP signal, which normally results in a program 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 preceding 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 program 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 program 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

Interposition of watchmalloc.so.1 fails innocuously if the target program is statically linked with respect to its malloc() routines. The system-supplied libraries -lmalloc and -lbsdmalloc are provided only in archive format and therefore programs linked with these libraries are immune to the interposition of watchmalloc.so.1.

FILES

/usr/lib/watchmalloc.so.1

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

SEE ALSO

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

SunOS 5.7  Last Revised 27 Feb 1997

NAME | SYNOPSIS | DESCRIPTION | WATCHPOINTS | LIMITATIONS | FILES | ATTRIBUTES | SEE ALSO