leaks(1)                System General Commands Manual                leaks(1)

NAME
     leaks - Search a process's memory for unreferenced malloc buffers

SYNOPSIS
     leaks [-cycles] [-nocontext] [-nostacks] [-exclude symbol] pid |
           executable name

DESCRIPTION
     leaks examines a specified process for malloc-allocated buffers which are
     not referenced by the program.  Such buffers waste memory; removing them
     can reduce swapping and memory usage.

     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.

     Normally, leaks considers a block referenced if a pointer to the block
     exists somewhere in memory.  With the -cycles option, leaks uses the
     stricter case that the block be referenced by a pointer from blocks known
     to be reachable by the program.  Any block referenced by a pointer in a
     global variable, or by a pointer from a reachable block, is also reach-
     able.

     For each leaked buffer allocated by malloc, 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 speci-
     fies 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 MallocHeapLogging environment variable is set, it finally 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 leaks.  Any allocations which
     were called from the named function are excluded from leaks's output.

     If the environment variable "MallocStackLogging" is set when the
     inspected program is started, leaks will also show the calling stack
     where the allocation occurred.  The environment variable turns on debug-
     ging 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 -nos-
     tacks option causes leaks to turn off display of the call stack.

WEAKNESSES
     Memory allocated via Carbon's NewHandle() function and then leaked will
     not be noted by leaks. Thus, running leaks on a Carbon application will
     show only a subset of all possible leaks.  The leaks reported will always
     be true leaks.

     MallocDebug will correctly find leaked blocks that were allocated via
     NewHandle, and permits easier browsing of leaked blocks.  However, Mal-
     locDebug does not detect leaks in circularly-linked structures or iden-
     tify groups of leaked, connected nodes; leaks's pointer analysis can cor-
     rectly identify such leaks.

SEE ALSO
     malloc(3), heap(1), malloc_history(1)

     Similar graphical applications are part of the developer tools for the
     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                             January 3, 2001                            BSD