leaks(1) BSD General Commands Manual leaks(1)

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

SYNOPSIS
     lleeaakkss [-nnooccoonntteexxtt] [-nnoossttaacckkss] [-eexxcclluuddee symbol] pid |
           partial-executable-name

DESCRIPTION
     lleeaakkss identifies leaked memory - memory that the application has allo-
     cated, but has been lost and cannot be freed.  Specifically, lleeaakkss 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.

     lleeaakkss 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, CoreFoundation, or C++ class, or a CFType, it
     also specifies the name and type of the class, and the binary image that
     implements 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 lleeaakkss 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 lleeaakkss.. 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
     lleeaakkss to turn off display of the call stack.

WWEEAAKKNNEESSSSEESS
     Memory allocated via Carbon's NewHandle() function and then leaked will
     not be noted by lleeaakkss.. 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), mallochistory(1), vmmap(1)

     The developer tools for the system also include a graphical application,
     /Developer/Applications/Instruments.app, that provides instruments that
     give information similar to that provided by lleeaakkss.. The Leaks instrument
     performs memory leak analysis.  The ObjectAlloc instrument graphically
     displays dynamic, real-time information about the object and memory use
     in an application, including backtraces of where the allocations occured.
     To use these instruments, the target application must be launched from
     Instruments.app, whereas lleeaakkss can examine existing processes.

BSD                             March 15, 2007                             BSD