malloc_history(1)         BSD General Commands Manual        malloc_history(1)

NAME
     malloc_history -- Show the malloc allocations that the process has per-
     formed

SYNOPSIS
     malloc_history process [-highWaterMark] address [address ...]
     malloc_history process -allBySize [-highWaterMark] [address ...]
     malloc_history process -allByCount [-highWaterMark] [address ...]
     malloc_history process -allEvents [-highWaterMark] [-showContent]
     malloc_history process -callTree [-highWaterMark] [-showContent]
                    [-invert] [-ignoreThreads] [-collapseRecursion]
                    [-chargeSystemLibraries] [address ...]

                    process is a pid, executable-name, or memory-graph-file

DESCRIPTION
     malloc_history inspects a given process and lists the malloc allocations
     performed by it.  malloc_history relies on information provided by the
     standard malloc library when malloc stack logging has been enabled for
     the target process.  See below for further information.

     The target process may be specified by pid or by full or partial name, or
     it can be the path of a memory graph file generated by leaks or the Xcode
     Memory Graph Debugger.

     If the -highWaterMark option is passed, malloc_history first scans
     through the all malloc stack log records to calculate the "high water
     mark" of allocated memory -- i.e., the highest amount of allocated memory
     used at any one time by the target process.  It then shows information
     about the malloc allocations that were live at that time, rather than
     currently alive in the target program.

     By specifying one or more addresses, malloc_history lists all allocations
     and deallocations of any malloc blocks that started at those addresses,
     or (starting in Mac OS X 10.6) of any malloc blocks that contained those
     addresses.  For each allocation, a stack trace describing who called mal-
     loc or free is listed.  If you do only wish to see events for malloc
     blocks that started at the specified address, you can grep the output for
     that address.  If -highWaterMark is passed, it only shows allocations and
     deallocations up to the high water mark.

     Alternatively, the -allBySize and -allByCount options list all alloca-
     tions that are currently live in the target process, or were live at the
     high water mark.  Frequent allocations from the same point in the program
     (that is, the same call stack) are grouped together, and output presented
     either from largest allocations to smallest, or most allocations to
     least.  If you also specify one or more addresses, this output is fil-
     tered to only show information for malloc blocks containing those
     addresses.

     The -allEvents option lists all allocation and free events, for all
     addresses, up to the current time or to the high water mark.  This output
     can be voluminous. If the -showContent option is passed, live allocations
     will have additional details as described for that option below.

     The -callTree option generates a call tree of the backtraces of malloc
     calls for live allocations in the target process, or for allocations that
     were live at the high water mark.  The call tree format is similar to the
     output from sample(1).  The resulting call tree can be filtered or pruned
     with the filtercalltree(1) tool for further analysis.  Additional options
     for the -callTree mode include:

           -showContent            Show the content of malloc blocks of vari-
                                   ous types, including C strings, Pascal
                                   strings (with a length byte at the start),
                                   and various objects including NSString,
                                   NSDate, and NSNumber.

           -invert                 Invert the call tree, so that malloc (and
                                   the allocated content, if the -showContent
                                   option was given) show at the top of the
                                   call trees.

           -ignoreThreads          Combine the call trees for all threads into
                                   a single call tree.

           -collapseRecursion      Collapse recursion within the call trees.

           -chargeSystemLibraries  Remove stack frames from all libraries in
                                   /System and /usr, while still charging
                                   their cost (number of calls, allocation
                                   size, and content) to the callers.

     All modes require the standard malloc library's debugging facility to be
     turned on.  To do this, set either the MallocStackLogging or MallocStack-
     LoggingNoCompact environment variable to 1 in the shell that will run the
     program.  If MallocStackLogging is used, then when recording events, if
     an allocation event for an address is immediately followed by a free
     event for the same address, both events are removed from the event log.
     If MallocStackLoggingNoCompact is used, then all such immediate alloca-
     tion/free pairs are kept in the event log, which can be useful when exam-
     ining all events for a specific address, or when using the -allEvents
     option.

     If both MallocStackLogging and MallocStackLoggingNoCompact are set, then
     MallocStackLogging takes precedence and MallocStackLoggingNoCompact is
     ignored.

     malloc_history is particularly useful for tracking down memory smashers.
     Run the program to be inspected with MallocStackLogging or MallocStack-
     LoggingNoCompact defined.  Also set the environment variable MallocScrib-
     ble; this causes the malloc library to overwrite freed memory with a
     well-known value(0x55), and occasionally checks freed malloc blocks to
     make sure the memory has not been overwritten since it was cleared.  When
     malloc detects the memory has been written, it will print out a warning
     that the buffer was modified after being freed.  You can then use
     malloc_history to find who allocated and freed memory at that address,
     and thus deduce what parts of the code might still have a pointer to the
     freed structure.

SEE ALSO
     malloc(3), heap(1), leaks(1), stringdups(1), vmmap(1), filtercalltree(1),
     DevToolsSecurity(1)

     The Xcode developer tools also include Instruments, a graphical applica-
     tion that can give information similar to that provided by
     malloc_history. The Allocations instrument graphically displays dynamic,
     real-time information about the object and memory use in an application,
     including backtraces of where the allocations occured.

BSD                              April 7, 2017                             BSD