Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.




vmmap(1)                  BSD General Commands Manual                 vmmap(1)

NAME
     vmmap -- Display the virtual memory regions allocated in a process

SYNOPSIS
     vmmap [-d seconds] [-w] [-resident] [-pages] [-interleaved] [-submap] [-allSplitLibs] [-noCoalesce]
           [-v] pid | partial-executable-name

DESCRIPTION
     vmmap displays the virtual memory regions allocated in a specified process, helping a programmer under-stand understand
     stand how memory is being used, and what the purposes of memory at a given address may be.  The process
     can be specified by process ID or by full or partial executable name.

OPTIONS
     -d seconds     Take two snapshots of the vm regions of the process, separated by the specified time,
                    and print the delta between those snapshots.

     -w, -wide      Print wide output.

     -resident      Show both the virtual and resident sizes for each region, in the form [ virtual/resi-dent]. virtual/resident].
                    dent].

     -pages         Print region sizes in page counts rather than kilobytes.

     -interleaved   Print all regions in ascending order of starting address, rather than printing all non-writable nonwritable
                    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.

     -v, -verbose   Equivalent to -w -resident -dirty -purge -submap -allSplitLibs -noCoalesce

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.

     If the -resident flag is given, then both the virtual and physical size of each region is shown, in the
     form [virtual/resident].  By default, the sizes are shown in kilobytes.  If the -pages flag is given,
     then the sizes are in number of 4KB 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.  Permis-sions Permissions
     sions 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 copy-onwrite
     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 -submap 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 flags 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.

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 mem-ory memory
     ory 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 occured.  The VM Tracker instrument in the Allocations template
     graphically displays information about the virtual memory regions in a process.

BSD                              Mar. 16, 2013                             BSD

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback