DESCRIPTION

     leaks identifies leaked memory -- memory that the application has allo-
     cated, but has been lost and cannot be freed.  Specifically, leaks exam-
     ines a specified process's memory for values that may be pointers to mal-
     loc-allocated buffers.  Any buffer reachable from a pointer in writable
     memory, a register, or on the stack is assumed to be memory in use.  Any
     buffer reachable from a pointer in a reachable malloc-allocated buffer is
     also assumed to be in use.  The buffers which are not reachable are
     leaks; the buffers could never be freed because no pointer exists in mem-
     ory to the buffer, and thus free() could never be called for these
     buffers.  Such buffers waste memory; removing them can reduce swapping
     and memory usage.  Leaks are particularly dangerous for long-running pro-
     grams, for eventually the leaks could fill memory and cause the applica-
     tion to crash.

     leaks requires one parameter -- either the process id or executable name
     of the process to examine.  It also takes several arguments for modifying
     its behavior.

     For each leaked buffer that is found, leaks displays the address of the
     leaked memory and its size.  If leaks can determine that the object is an
     instance of an Objective C or CoreFoundation class, it also specifies the
     name of the class.  If the -nocontext option is not specified, it then
     displays a hexadecimal dump of the contents of the memory.  If the Mal-
     locStackLogging environment variable was set when the application was
     launched, leaks also displays a stack trace describing where the buffer
     was allocated.

     The -nocontext option causes leaks to withhold a hex dump of the leaked
     memory.  Although this information can be useful for recognizing the con-
     tents of the buffer and understanding why it might be leaked, it can also
     provide overwhelming detail.  This flag will hopefully reduce your
     stress.

     The -exclude option allows you to ignore functions that allocate memory
     which is from a well-known leak that you don't want to keep hearing
     about, or might be falsely labelled a leak by leaks. Any allocations
     which were called from the named function are excluded from leaks's out-
     put.

     If the environment variable "MallocStackLogging" is set when the
     inspected program is started, leaks will also show the calling stack
     where the allocation occurred, providing essential hints about why the
     leak is occurring.  The environment variable turns on debugging support
     in the standard malloc library; leaks then snoops at this information in
     the target to find the call stack.  If the call stack information is
     being displayed, and you wish to suppress it, the -nostacks option causes
     leaks to turn off display of the call stack.

WEAKNESSES

     Memory allocated via Carbon's NewHandle() function and then leaked will
     system.  MallocDebug.app is a graphical application that also provides
     information about heap-allocated memory.  It also performs leak analysis
     correctly for programs using the Carbon libraries.

BSD                              June 19, 2002                             BSD