leaks(1) General Commands Manual leaks(1)
NAME
leaks – Search a process's memory for unreferenced malloc buffers
SYNOPSIS
leaks [options] pid | partial-executable-name | memory-graph-file
leaks [options] -atExit -- command
Options:
[-list] [-groupByType] [-nostacks] [-nosources] [-quiet] [-exclude symbol]
[-outputGraph path] [-fullContent] [-readonlyContent] [-noContent]
[-diffFrom=<memgraph>] [-traceTree address] [-referenceTree]
[-autoreleasePools] [-debug=<mode>]
DESCRIPTION
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.
MEMORY GRAPH FILES
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.
OPTIONS
-list Print the leaks as a list ("classic"-style) rather than as a
tree. Warning: this option may be removed in the future.
-groupByType When printing a tree of leaked objects, group the children of
a node in the tree by type, rather than showing individual
instances.
-nostacks Do not print backtraces of leaked blocks even if the target
process has the MallocStackLogging environment variable set.
-nosources Do not print sourceFile:lineNumber in backtraces. This can
improve performance when examining a process with a huge
number of debug symbols.
-quiet Do not print process description header or binary image list.
-exclude symbol
Exclude leaked blocks whose backtraces include the specified
symbol. This option can be repeated for multiple symbols.
This allows ignoring leaks that, for example, are allocated
in libraries for which you do not have source code.
-outputGraph path
Generate a memory graph file containing information about all
VM and malloc nodes, and the references between them. path
can be a path to a file, or just a directory name; in the
latter case a filename with the ".memgraph" suffix will be
generated.
By 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 When generating a memory graph file, include descriptions of
the content of various objects, as would be shown by 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
When running leaks against a live target process, print
descriptions of the content of memory only if they are backed
by read-only memory. (Read-only content is the default when
generating memory graph files.)
-noContent Do not print the descriptions of the content of leaked
memory, or save descriptions of allocation memory into memory
graph files. Although that information can be useful for
recognizing the contents of the buffer and understanding why
it might be leaked, it could expose confidential information
from the process if you, for example, file bug reports with
that output included.
-diffFrom=<memgraph>
Show only the new leaks since the specified memgraph.
-traceTree address
Print a reverse tree of references, from the given block up
to the process 'roots' (e.g., global data, registers, or
locations on stacks) to the given block. This is useful for
determining what is holding onto a buffer such that it has
not been freed, and is similar to the information shown in
the Xcode Memory Graph Debugger.
-referenceTree
Print a top-down tree of all malloc allocations and
dynamically-allocated VM regions in the process. This can be
useful for getting an overall sense of how memory is held by
the process. The -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
Print the contents of all autorelease pools of all threads of
the process, and trees of memory that are only held by those
allocations. If the autorelease pool got popped then that
additional memory that is only held by autorelease pool
entries would get released.
-debug=[mode]
This flag offers several additional more detailed modes of
output, intended for debugging and deeper investigations. Use
-debug=help to get more information about various debug
modes.
-atExit -- command
Launches the specified command and runs leaks 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/
ENVIRONMENT
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.
EXIT STATUS
The leaks command exits with one of the following values:
0 No leaks were detected.
1 One or more leaks were detected.
>1 An error occurred.
SEE ALSO
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.
macOS 12.1 April 26, 2021 macOS 12.1