This manual page is part of Xcode Tools version 3.2.2

Reading manual pages

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

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

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

DESCRIPTION
     leaks identifies leaked memory -- memory that the application has allocated, but has been lost and can-not cannot
     not be freed.  Specifically, leaks examines a specified process's memory for values that may be point-ers pointers
     ers to malloc-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 memory 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 programs, for eventually the leaks
     could fill memory and cause the application 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, 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 MallocStackLogging 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 informa-tion information
     tion can be useful for recognizing the contents 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 alloca-tions allocations
     tions 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, 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 informa-tion information
     tion 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 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, MallocDebug does not detect leaks in circularly-linked structures
     or identify groups of leaked, connected nodes; leaks's pointer analysis can correctly identify such
     leaks.

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

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

BSD                                            March 15, 2007                                            BSD