malloc_history(1) | General Commands Manual | malloc_history(1) |
malloc_history
—
Show the malloc and anonymous VM allocations that the
process has performed
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 ]
[-virtual ] [address ... |
<classes-pattern>]
process is a pid, executable-name, or memory-graph-file |
malloc_history
inspects a given process
and lists the malloc and anonymous VM allocations performed by it. Anonymous
VM allocations are from calls such as mach_vm_allocate that allocate raw
Virtual Memory that is not backed by a file. Allocations of the VM regions
underlying the malloc heaps are ignored.
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 and anonymous VM regions that were live at that time, rather
than currently alive in the target program.
The -highWaterMark
option does not work
with memory graph files since they only contain stack logs for active
allocations, not full history.
By specifying one or more addresses,
malloc_history
lists all allocations and
deallocations of any malloc blocks or VM regions that started at or
contained those addresses. For each allocation, a stack trace describing who
called malloc or free, or mach_vm_allocate, mmap, or mach_vm_deallocate is
listed. If you do only wish to see events for malloc blocks and VM regions
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 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 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 and anonymous VM regions for live
allocations in the target process, or for allocations that were live at the
high water mark. The call tree can be filtered to backtraces of specific
allocations or classes, by passing one or more addresses or a
<classes-pattern>.
The <classes-pattern> regular expression is interpreted as an extended (modern) regular expression as described by the re_format(7) manual page. "malloc" or "non-object" can be used to refer to blocks that are not of any specific type. Examples of valid classes-patterns include:
The <classes-pattern> pattern can be followed by an optional allocation size specifier, which can be one of the following forms. The square brackets are required. The size can include a 'k' suffix for kilobytes, or an 'm' suffix for megabytes:
Examples of <classes-pattern> with size specifications include:
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
-invert
-showContent
option was given) show at the top of
the call trees.-ignoreThreads
-collapseRecursion
-chargeSystemLibraries
-virtual
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 allocation/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 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.
To see backtraces of allocations by class type or malloc size, run this command:
% malloc_history <process> -callTree -invert -showContent
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.
Oct. 7, 2019 | macOS 14.6 |