Mac Developer Library Developer


This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.

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

     malloc_history -- Show the malloc allocations that the process has performed

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

     malloc_history inspects a given process and lists the malloc allocations performed by it.  The target
     process may be specified by pid or by full or partial name.  malloc_history relies on information pro-vided provided
     vided by the standard malloc library when malloc stack logging has been enabled for the target process.
     See below for further information.

     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 alloca-tions allocations
     tions 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 mal-loc malloc
     loc 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 malloc 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 deal-locations deallocations
     locations up to the high water mark.

     Alternatively, the -allBySize and -allByCount options list all allocations 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 filtered to only show information for malloc blocks containing those

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

     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 various 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 MallocStackLoggingNoCompact 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 allocation/free
     tion/free pairs are kept in the event log, which can be useful when examining 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 MallocStackLoggingNoCompact defined.  Also set the environment
     variable MallocScribble; 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 over-written overwritten
     written 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.

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

     The Xcode developer tools also include Instruments, a graphical application 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                              Mar. 16, 2013                             BSD

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.