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

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

     -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

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

                   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.

                   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.

                   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.

                   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.

                   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

     -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

                   % 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:

     0     No leaks were detected.
     1     One or more leaks were detected.
     >1    An error occurred.

     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

macOS 12.1                       April 26, 2021                       macOS 12.1