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)
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
|