leaks(1)						    BSD General Commands Manual 						  leaks(1)

NAME

     leaks -- Search a process's memory for unreferenced malloc buffers

SYNOPSIS

     leaks pid | partial-executable-name | memory-graph-file [-list] [-groupByType] [-nocontext] [-nostacks] [-nosources] [-quiet]
	   [-exclude symbol] [-trace address] [-outputGraph path] [-fullContent] [-atExit]

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 buf-
     fers waste memory; removing them can reduce swapping and memory usage.  Leaks are particularly dangerous for long-running programs, for even-
     tually 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.

     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 ".mem-
     graph".  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.

     -nocontext    Do not print the string or hex representation of leaked memory.  Although that information can be useful for recognizing the
		   contents of the buffer and understanding why it might be leaked, it can also provide overwhelming detail, and could expose con-
		   fidential information from your process if you, for example, file bug reports with that output included.

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

     -trace address
		   Print chains of references from 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.

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

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

     -atExit	   Launches the specified process and runs leaks when the process exits.  The process to launch must be the end of the command,
		   and proceeded by '--': leaks -atExit -- /MyPath/MyProgram -MyArg

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 back-
     traces of where the allocations occurred.	The Leaks instrument performs memory leak analysis.

BSD
								    May 6, 2018 							       BSD