heap

heap(1)                      General Commands Manual                     heap(1)

NAME
     heap – List all the malloc-allocated buffers in the process's heap

SYNOPSIS
     heap [-s | -sortBySize] [-z | -zones] [-guessNonObjects] [-sumObjectFields]
          [-showSizes] [-addresses all | <classes-pattern>] [-noContent]
          pid | partial-executable-name | memory-graph-file

DESCRIPTION
     heap lists the objects currently allocated on the heap of the specified
     process, as well as summary data.  Objects are categorized by class name,
     type (Objective-C, C++, or CFType), and binary image.  C++ objects are
     identified by the vtable referenced from the start of the object, so with
     multiple inheritance this may not give the precise class of the object.

     The binary image identified for a class is the image which implements the
     class, not necessarily the binary image which caused the objects to be
     allocated at runtime, or which "owns" those objects.

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

     The following options are available:

     -s | -sortBySize
             Sort output by total size of class instances, rather than by count.

     -z | -zones
             Show the output separated out into the different malloc zones,
             instead of an aggregated summary of all zones.

     -guessNonObjects
             Look through the memory contents of each Objective-C object to find
             pointers to malloc'ed blocks (non-objects), such as the variable
             array hanging from an NSArray.  These referenced blocks of memory
             are identified as their offset from the start of the object (say
             "__NSCFArray[12]").  The count, number of bytes, and average size
             of memory blocks referenced from each different object offset
             location are listed in the output.

     -sumObjectFields
             Do the same analysis as with the -guessNonObjects option, but add
             the sizes of those referenced non-object fields into the entries
             for the corresponding objects.

     -showSizes
             Show the distribution of each malloc size for each object, instead
             of summing and averaging the sizes in a single entry.

     -diffFrom=<memgraph>
             Show only the new objects since the specified memgraph.

     -addresses all | <classes-pattern>
             Print the addresses of all malloc blocks found on the heap in
             ascending address order, or the addresses of those objects whose
             full class name is matched by the regular expression <classes-
             pattern>.  The string "all" indicates that the addresses of all
             blocks should be printed.

             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:
                   __NSCFString
                   'NS.*'
                   '__NSCFString|__NSCFArray'
                   '.*(String|Array)'
                   malloc
                   non-object
                   malloc|.*String

             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:
                   [size]
                   [lowerBound-upperBound]
                   [lowerBound+]
                   [-upperBound]

             Examples of <classes-pattern> with size specifications include:
                   malloc[2048]   // all malloc blocks of size 2048
                   malloc[1k-8k]  // all malloc blocks between 1k and 8k
                   CFData[50k+]   // all CFData objects 50k or larger
                   [-1024]        // all allocations 1024 bytes or less

     -noContent
             Do not show object content in -addresses mode.

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

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

macOS 12.1                        Oct. 7, 2019                        macOS 12.1