leaks(1) | General Commands Manual | leaks(1) |
leaks
— Search a
process's memory for unreferenced malloc buffers
leaks |
[options] pid | partial-executable-name | memory-graph-file |
leaks |
[options] -atExit --
command |
[-list
]
[-groupByType
] [-nostacks
]
[-nosources
] [-quiet
]
[-exclude
symbol]
[-outputGraph
path]
[-fullContent
]
[-readonlyContent
]
[-noContent
]
[-fullStackHistory
]
[-diffFrom=<memgraph>
]
[-traceTree
address]
[-referenceTree
]
[-autoreleasePools
]
[-debug=<mode>
]
[-conservative
]
leaks
identifies leaked memory -- memory
that the application has allocated, but has been lost and cannot be freed.
Specifically, leaks
examines a specified process's
memory for values that may be pointers to malloc-allocated buffers. Any
buffer reachable from a pointer in writable global memory (e.g., __DATA
segments), 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 argument -- either the
process ID or the full or partial executable name of the process to examine,
or the pathname of a memory graph file generated by
leaks
or the Xcode Memory Graph Debugger. (Unless
the -atExit
--
command argument is given, see below for more
details.)
Once the leaked buffers have been identified,
leaks
analyzes them to find "root leaks"
(those which are not referenced by any other buffer) and "root
cycles" (cycles of objects which reference or retain each other, but
which are not referenced by any other buffer outside the cycle). Then, it
identifies the tree of buffers which are referenced by those root leaks and
root cycles, if any. leaks
then prints each such
"leak tree".
If the MallocStackLogging environment variable was set when the
application was launched, leaks
also prints a stack
trace describing where the buffer was allocated.
A memory graph file archives the memory state of a process for
further analysis at a later time, on a different machine, or by other
people. It includes information about all VM and malloc nodes in the
process, and the references between them. Memory graph files can be
generated by leaks
using the
-outputGraph
option (and the
-fullContent
option if desired), or by examining a
live process with the Xcode Memory Graph Debugger then using the Export
Memory Graph menu item from the File menu. The standard filename suffix for
memory graph files is ".memgraph". These files can be used as
input to various commands including leaks,
heap,
stringdups,
vmmap,
malloc_history,
footprint,
and the Xcode Memory Graph Debugger.
-list
-groupByType
-nostacks
-nosources
-quiet
-exclude
symbol-outputGraph
pathBy default (for security) when generating a memory graph file,
descriptions of the content of some objects will be included but ONLY if
they are backed by read-only memory in Mach-O binary images or the dyld
shared cache. To store full content pass the
-fullContent
flag.
-fullContent
heap <pid>
-addresses all
, and as needed by stringdups
<pid>
. (Full content is the default when targeting a live
process, without generating a memory graph file.)-readonlyContent
-noContent
-fullStackHistory
-diffFrom=<memgraph>
-traceTree
address-referenceTree
-groupByType
argument can also be passed to
summarize the data.
In this reference tree mode, each allocation only appears once in the output. Some attempt is made to prioritize which reference to an allocation should be considered as the "owning" allocation to decide where in the tree to show the allocation, but since allocations often have several or numerous references to them (some of which may be false or stale references) and only one can be the "parent" in this reference tree output, sometimes allocations are shown in the wrong place in the tree.
-autoreleasePools
-debug=[mode]
-debug=help
to get more information about various
debug modes.-conservative
-atExit
--
commandleaks
when
that process exits. The -atExit
argument should be
the last argument, followed by -- and the command to launch. For example:
$ leaks -quiet -atExit -- /bin/ls -lt /tmp/
Using -atExit
will automatically set
MallocStackLogging=lite for the specified command so that stack
backtraces can be shown for leaked allocations. To use a different
setting of that env var, such as YES or NO, you can set the env var
prior to running leaks. For example:
$ MallocStackLogging=YES leaks -quiet -atExit -- /bin/ls -lt /tmp/
The leaks
command may detect more leaks if
the target process is run with the MallocScribble environment variable. If
this variable is set then when malloc blocks are deallocated they are filled
with 0x55 bytes, thus overwriting any "stale" data such as
pointers remaining in those blocks. This reduces the number of false
pointers remaining in the process memory.
The leaks
command exits with one of the
following values:
malloc(3), heap(1), malloc_history(1), stringdups(1), vmmap(1), footprint(1), DevToolsSecurity(1)
The Xcode Memory Graph Debuggger graphically shows malloc blocks and VM regions (both leaked and non-leaked), and the references between them.
The Xcode developer tools also include Instruments, a graphical
application that can give information similar to that provided by
leaks.
The Allocations instrument graphically
displays dynamic, real-time information about the object and memory use in
an application, including backtraces of where the allocations occurred. The
Leaks instrument performs memory leak analysis.
March 15, 2022 | macOS 14.6 |