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] [-fullStackHistory] [-diffFrom=<memgraph>] [-traceTree
     address] [-referenceTree] [-autoreleasePools] [-debug=<mode>]
     [-conservative]

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.

     -fullStackHistory
                   When generating a memory graph file, include all available
                   MallocStackLogging backtraces, including those for
                   historical allocations that have been freed.

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

     -conservative
                   Ignore type information and scan byte-by-byte for pointers,
                   conservatively assuming that all references are owning
                   references.

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

                   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/

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.

CAVEATS
     All memory sizes are given in binary-prefixed units. For example, "1K"
     refers to 1024 bytes.

macOS 15.2                      March 15, 2022                      macOS 15.2