.\" Copyright (c) 2000-2022  Apple Inc. All rights reserved.
.Dd Feb. 8, 2022
.Dt "heap" 1
.Os
.Sh NAME
.Nm heap
.Nd List all the malloc-allocated buffers in the process's heap
.Sh SYNOPSIS
.Nm heap
.Op Fl s | Fl sortBySize
.Op Fl z | Fl zones
.Op Fl guessNonObjects
.Op Fl sumObjectFields
.Op Fl showSizes
.Op Fl addresses Ar all | Ar <classes-pattern>
.Op Fl noContent
.Ar pid | partial-executable-name | memory-graph-file
.Sh DESCRIPTION
.Nm 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.
.Pp
If the target process is running with MallocStackLogging, then
.Nm heap
attempts to identify the types of "non-object" allocations, using the form
"<allocation-call> in <caller>". The <caller> is determined by walking up the
allocation stack backtrace (if available) to find the symbol name of the
function that called an "allocation function", such as
malloc, calloc, realloc, C++ "operator new", strndup, various internal functions
of libc++.1.dylib, etc. If <caller> is a C++ function, the type name
is created by simplifying the demangled symbol name by removing the
return type, the "__1::" substrings from use of llvm's libc++abi.dylib,
and standard arguments such as "std::__1::allocator<T>"."
.Pp
For example, this type information:
.Bd -literal -offset indent -compact
malloc in std::basic_string<char>::basic_string<std::nullptr_t>(char const*)  C++     Metal
.Ed
.Pp
is determined from the backtrace:
.Bl -tag -offset indent -compact
.It _malloc_zone_malloc  (in libsystem_malloc.dylib)
.It operator new(unsigned long)  (in libc++abi.dylib)
.It std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >::basic_string<std::nullptr_t>(char const*)  (in Metal)
.It ...
.El
.Pp
The binary image identified for a class is the image which implements the class.
For types derived from allocation backtraces, the binary image is that of <caller>.
.Pp
.Sh OPTIONS
.Nm 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
.Nm leaks
or the Xcode Memory Graph Debugger.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl s | Fl sortBySize
Sort output by total size of class instances, rather than by count. In
.Nm -addresses
mode sort output by allocation size.
.It Fl z | Fl zones
Show the output separated out into the different malloc zones, instead of an aggregated summary of all zones.
.It Fl H | Fl humanReadable
"Human-readable" output. Use unit suffixes: K, M, G, and T in order to reduce the number of digits to three or less using base 2 for sizes.
.It Fl 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.
.It Fl sumObjectFields
Do the same analysis as with the
.Fl guessNonObjects
option, but add the sizes of those referenced non-object fields into the entries for the corresponding objects.
.It Fl showSizes
Show the distribution of each malloc size for each object, instead of summing and averaging the sizes in a single entry.
.It Fl diffFrom=<memgraph>
Show only the new objects since the specified memgraph.
.It Fl addresses Ar all | Ar <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.
.Pp
When combined with
.Nm —-sortBySize
option, print malloc blocks in descending order of sizes.
.Pp
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:
.Bl -tag -offset indent -compact
.It __NSCFString
.It 'NS.*'
.It '__NSCFString|__NSCFArray'
.It '.*(String|Array)'
.It malloc
.It non-object
.It malloc|.*String
.El
.Pp
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:
.Bl -tag -offset indent -compact
.It [size]
.It [lowerBound-upperBound]
.It [lowerBound+]
.It [-upperBound]
.El
.Pp
Examples of <classes-pattern> with size specifications include:
.Bl -tag -offset indent -compact -width "malloc[1k-8k]"
.It malloc[2048]
// all malloc blocks of size 2048
.It malloc[1k-8k]
// all malloc blocks between 1k and 8k
.It CFData[50k+]
// all CFData objects 50k or larger
.It [-1024]
// all allocations 1024 bytes or less
.El
.It Fl noContent
Do not show object content in -addresses mode.
.El
.Sh SEE ALSO
.Xr malloc 3 ,
.Xr leaks 1 ,
.Xr malloc_history 1 ,
.Xr stringdups 1 ,
.Xr vmmap 1 ,
.Xr DevToolsSecurity 1
.Pp
The Xcode developer tools also include Instruments, a graphical application that can give information similar to that provided by
.Nm 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.
.Sh CAVEATS
All memory sizes are given in binary-prefixed units. For example, "1K" refers to 1024 bytes.