manpagez: man pages & more
man leaks(1)
Home | html | info | man

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 [-nocontext]
           [-nostacks] [-nosources] [-quiet] [-exclude symbol]
           [-trace address] [-outputGraph path] [-fullContent] [-atExit]


DESCRIPTION

     leaks identifies leaked memory -- memory that the application has allo-
     cated, but has been lost and cannot be freed.  Specifically, leaks exam-
     ines a specified process's memory for values that may be pointers to mal-
     loc-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 particu-
     larly 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 par-
     tial executable name of the process to examine, or the pathname of a mem-
     ory graph file generated by leaks or the Xcode Memory Graph Debugger.

     For each leaked buffer that is found, leaks prints the address of the
     leaked memory and its size.  If leaks can determine that the object is an
     instance of an Objective-C, CoreFoundation, or C++ class, or a CFType, it
     also specifies the name and type of the class, and the binary image that
     implements the class.  It then prints a string or hexadecimal representa-
     tion of the contents of the memory, unless the -nocontext option was
     specified.

     If the MallocStackLogging environment variable was set when the applica-
     tion 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, and the Xcode Memory Graph
     Debugger.


OPTIONS

     -nocontext     Do not print the string or hex representation of leaked
                    memory.  Although that information can be useful for rec-
                    ognizing the contents of the buffer and understanding why
                    it might be leaked, it can also provide overwhelming
                    detail, and could expose confidential 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 tar-
                    get process has the MallocStackLogging environment vari-
                    able 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 speci-
                    fied 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 hold-
                    ing 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 mem-
     ory.


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),
     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 applica-
     tion that can give information similar to that provided by leaks. The
     Allocations instrument graphically displays dynamic, real-time informa-
     tion 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                              July 27, 2017                             BSD

Mac OS X 10.12.6 - Generated Sun Oct 29 07:40:03 CDT 2017
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.