This manual page is part of Xcode Tools version 3.2

Reading manual pages

heap(1)                                  BSD General Commands Manual                                 heap(1)

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

SYNOPSIS
     heap [-guessNonObjects] [-sumObjectFields] [-showSizes] [-addresses all | <classes-pattern>] pid |
          partial-executable-name

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 parameter -- either a process ID or a full or partial executable name.

     The following options are available:

     -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 "NSCFAr-ray[12]"). "NSCFArray[12]").
             ray[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.

     -addresses all | <classes-pattern>
             Print the addresses of all objects 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 (both objects and non-objects) nonobjects)
             objects) 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.  Note that
             toll-freed-bridged CoreFoundation and Foundation classes have the "NSCF" prefix rather than
             just "NS" or "CF".  Examples of valid classes-patterns include:

                   NSCFString
                   'NS.*'
                   'NSCFString|NSCFArray'
                   '.*(String|Array)'
                   non-object

EXAMPLE
     The -addresses option can be used to find over-rooted objects in the autozone in an Objective-C appli-cation application
     cation running with Garbage Collection.  Over-rooted objects have more references to them than
     expected, thus preventing the memory from being collected (and thus, causing a memory leak).  One way
     to find over-rooted objects is:

     1.   In a Terminal window, run 'top -u' and observe the VSIZE of the target application.

     2.   Perform an action in the application, and undo it.  Perform the action action, and undo it again.
          If VSIZE grows and does not shrink again, there may be a leak caused by over-rooted objects.

     3.   Run 'heap -addresses all <target-pid>' and save the output into a file.

     4.   Perform the action again, and undo it again.

     5.   Run 'heap -addresses all <target-pid>' again and save the output into a second file.

     6.   Run 'opendiff <output1> <output2> to compare the output of the two heap runs in FileMerge.  Typi-cally, Typically,
          cally, it will be fairly apparent that whatever objects should have been reaped after the undo
          were not.

     7.   Attach to the target application with gdb for further analysis.  To see the roots of a particular
          object of interest, do the following:

          % gdb
          (gdb) attach <target-pid>
          (gdb) info gc-roots <address-printed-by-heap>
          (gdb) detach
          (gdb) quit

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

     The developer tools for the system also include a graphical application, /Developer/Applica-tions/Instruments.app, /Developer/Applications/Instruments.app,
     tions/Instruments.app, that provides instruments that give information similar to that provided by
     heap. The ObjectAlloc instrument graphically displays dynamic, real-time information about the object
     and memory use in an application, including backtraces of where the allocations occured.  The Leaks
     instrument in performs memory leak analysis.  To use these instruments, the target application must be
     launched from Instruments.app, whereas heap can examine existing processes.  heap also has the advan-tage advantage
     tage that the data can be immediately parsed by text-based tools, and impacts the system less because
     it is not a full graphical application.

BSD                                             Nov. 3, 2008                                             BSD