vmmap(1) General Commands Manual vmmap(1)
NAME
vmmap – Display the virtual memory regions allocated in a process
SYNOPSIS
vmmap [-s] [-w] [-v] [-pages] [-interleaved] [-submap] [-allSplitLibs]
[-noCoalesce] [-summary]
pid | partial-executable-name | memory-graph-file [address]
DESCRIPTION
vmmap displays the virtual memory regions allocated in a specified
process, helping a programmer understand how memory is being used, and
what the purposes of memory at a given address may be.
vmmap 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.
If the optional address is given, information is only shown for the VM
region containing that address (if any) and the regions around it.
OPTIONS
-s, -sortBySize
Print sorted regions and malloc zones by size (dirty +
swapped)
-w, -wide Print wide output, to show full paths of mapped files.
-v, -verbose Equivalent to -w -submap -allSplitLibs -noCoalesce
-pages Print region sizes in page counts rather than bytes.
-interleaved Print all regions in ascending order of starting address,
rather than printing all non-writable regions followed by
all writable regions.
-submap Print information about VM submaps.
-allSplitLibs Print information about all shared system split libraries,
even those not loaded by this process.
-noCoalesce Do not coalesce adjacent identical regions. Default is to
coalesce for more concise output.
-summary Print only the summary of VM usage, not the individual
region detail.
EXPLANATION OF OUTPUT
For each region, vmmap describes the starting address, ending address,
size of the region (in kilobytes or pages), read/write permissions for
the page, sharing mode for the page, and the purpose of the pages.
The size of the virtual memory region represents the virtual memory pages
reserved, but not necessarily allocated. For example, using the
vm_allocate Mach system call reserves the pages, but physical memory
won't be allocated for the page until the memory is actually touched. A
memory-mapped file may have a virtual memory page reserved, but the pages
are not instantiated until a read or write happens. Thus, this size may
not correctly describe the application's true memory usage.
By default, the sizes are shown in kilobytes or megabytes. If the -pages
flag is given, then the sizes are in number of VM pages.
The protection mode describes if the memory is readable, writable, or
executable. Each virtual memory region has a current permission, and a
maximum permission. In the line for a virtual memory region, the current
permission is displayed first, the maximum permission second. For
example, the first page of an application (starting at address
0x00000000) permits neither reads, writes, or execution ("---"), ensuring
that any reads or writes to address 0, or dereferences of a NULL pointer
immediately cause a bus error. Pages representing an executable always
have the execute and read bits set ("r-x"). The current permissions
usually do not permit writing to the region. However, the maximum
permissions allow writing so that the debugger can request write access
to a page to insert breakpoints. Permissions for executables appear as
"r-x/rwx" to indicate these permissions.
The share mode describes whether pages are shared between processes,and
what happens when pages are modified. Private pages (PRV) are pages only
visible to this process. They are allocated as they are written to, and
can be paged out to disk. Copy-on-write (COW) pages are shared by
multiple processes (or shared by a single process in multiple locations).
When the page is modified, the writing process then receives its own
private copy of the page. Empty (NUL) sharing implies that the page does
not really exist in physical memory. Aliased (ALI) and shared (SHM)
memory is shared between processes.
The share mode typically describes the general mode controlling the
region. For example, as copy-on-write pages are modified, they become
private to the application. Even with the private pages, the region is
still COW until all pages become private. Once all pages are private,
then the share mode would change to private.
The far left column names the purpose of the memory: malloc regions,
stack, text or data segment, etc. For regions loaded from binaries, the
far right shows the library loaded into the memory.
If the -submaps flag is given, then vmmap's output includes descriptions
of submaps. A submap is a shared set of virtual memory page descriptions
that the operating system can reuse between multiple processes. Submaps
minimize the operating system's memory usage by representing the virtual
memory regions only once. Submaps can either be shared by all processes
(machine-wide) or local to the process (process-only). (Understanding
where submaps are located is irrelevant for most developers, but may be
interesting for anyone working with low levels of the virtual memory
system.)
For example, one submap contains the read-only portions of the most
common dynamic libraries. These libraries are needed by most programs on
the system, and because they are read-only, they will never be changed.
As a result, the operating system shares these pages between all the
processes, and only needs to create a single data structure to describe
how this memory is laid out in every process.
That section of memory is referred to as the "split library region", and
it is shared system-wide. So, technically, all of the dynamic libraries
that have been loaded into that region are in the VM map of every
process, even though some processes may not be using some of those
libraries. By default, vmmap shows only those shared system split
libraries that have been loaded into the specified target process. If
the -allSplitLibs flag is given, information about all shared system
split libraries will be printed, regardless of whether they've been
loaded into the specified target process or not.
If the contents of a machine-wide submap are changed -- for example, the
debugger makes a section of memory for a dylib writable so it can insert
debugging traps -- then the submap becomes local, and the kernel will
allocate memory to store the extra copy.
% FRAG, fragmentation, in the MALLOC ZONE summary is computed by the
following method:
% FRAG = 100 - (100 * Allocated / (Dirty + Swapped))
Dirty and swapped are memory which has been written to by the process.
Allocated is the number of bytes currently allocated from malloc.
SEE ALSO
heap(1), leaks(1), malloc_history(1), stringdups(1), lsof(8)
The heap, leaks, and malloc_history commands can be used to look at
various aspects of a process's memory usage.
The lsof command can be used to get a list of open and mapped files in
one or more processes, which can help determine why a volume can't be
unmounted or ejected, for example.
The Xcode developer tools also include Instruments, a graphical
application that can give information similar to that provided by vmmap.
The Allocations instrument graphically displays dynamic, real-time
information about the object and memory use in an application (including
VM allocations), as well as backtraces of where the allocations occurred.
The VM Tracker instrument in the Allocations template graphically
displays information about the virtual memory regions in a process.
CAVEATS
All memory sizes are given in binary-prefixed units. For example, "1K"
refers to 1024 bytes.
macOS 15.2 August 9, 2022 macOS 15.2