PMAP(1)                 NetBSD General Commands Manual                 PMAP(1)

NAME
     pmap -- display process memory map

SYNOPSIS
     pmap [-adlmPRsv] [-A address] [-D number] [-E address] [-M core]
          [-N system] [-p pid] [-S address] [-V address] [pid ...]

DESCRIPTION
     The pmap utility lists the virtual memory mappings underlying the given
     process.  The start address of each entry is always given, and, depending
     on the options given, other information such as the end address, the
     underlying file's device and inode numbers, and various protection infor-
     mation will be displayed, along with the path to the file, if such data
     is available.

     By default, pmap displays information for its parent process, so that
     when run from a shell prompt, the shell's memory information is dis-
     played.  If other PIDs are given as arguments on the command line, infor-
     mation for those processes will be printed also.  If the special PID of 0
     is given, then information for the kernel's memory map is printed.

     The options are as follows:

     -A address   Dumps the vm_amap structure found at address.

     -a           Display ``all'' information from the process's memory map.
                  This output mode is an amalgam of the contents of the
                  Solaris, Linux, and NetBSD style output modes.

     -D number    Enable various debug facilities.  The number is a bit mask
                  of the values:

                  0x01    dump the process's vmspace structure
                  0x02    dump the process's vm_map structure
                  0x04    dump the vm_map.header structure
                  0x08    dump each vm_map_entry in its entirety
                  0x10    dump the vm_amap structure attached to the
                          vm_map_entry, if applicable
                  0x20    dump the vm_amap slot data, if present (requires
                          0x10)
                  0x40    dump the vm_anon data from the am_anon array, if
                          present (requires 0x20)
                  0x1000  dump the namei cache as it is traversed

     -d           Dumps the vm_map and vm_map_entry structures in a style sim-
                  ilar to that of ddb(4).  When combined with the -v option,
                  the device number, inode number, name, vnode addresses, or
                  other identifying information from the vm_map_entries will
                  be printed.

     -E address   Dumps the vm_map_entry structure found at address.

     -l           Dumps information in a format like the contents of the maps
                  pseudo-file under the /proc file system which was, in turn,
                  modeled after the similarly named entry in the Linux /proc
                  file system.  When combined with the -v option, identifiers
                  for all entries are printed.

     -M core      Extract values associated with the name list from the speci-
                  fied core instead of the default /dev/kmem.

     -m           Dumps information in the same format as the map pseudo-file
                  of the /proc file system.  When the -v option is also given,
                  device number, inode number, and filename or other identify-
                  ing information is printed.

     -N system    Extract the name list from the specified system instead of
                  the default /netbsd.

     -P           Causes pmap to print information about itself.

     -p pid       Tells pmap to print information about the given process.  If
                  -p pid occurs last on the command line, the -p is optional.

     -R           Recurse into submaps.  In some cases, a vm_map_entry in the
                  kernel will point to a submap.  Using this flag tells pmap
                  to print the entries of the submap as well.  The submap out-
                  put is indented, and does not affect any total printed at
                  the bottom of the output.

     -S address   Dumps the vmspace structure found at address.

     -s           The Solaris style output format, modeled after the Solaris
                  command of the same name.  This is the default output style.

     -V address   Dumps the vm_map structure found at address.  Note that if
                  you print the vm_map of a process, there may not be a way to
                  properly determine which map entries are related to the
                  stack.

     -v           Verbose output.  When used with -d, -l, or -m, more informa-
                  tion is printed, possibly including device and inode num-
                  bers, file path names, or other identifying information.  If
                  specified more than once, a small note will be printed in
                  between two entries that are not adjacent, making the visual
                  identification of spaces in the process's map easier to see,
                  that indicates the number of pages and the amount of memory
                  space that is skipped.

     The -P and -p options override each other, so the last one to appear on
     the command line takes effect.  If you do wish to see information about
     pmap and another process as the same time, simply omit the -p and place
     the extra PID at the end of the command line.

EXIT STATUS
     The pmap utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
     While the meaning of most of the output is self-evident, some pieces of
     it may appear to be a little inscrutable.

     Here is a portion of the default output from pmap being run at an sh(1)
     prompt showing the starting address of the map entry, the size of the map
     entry, the current protection level of the map entry, and either the name
     of the file backing the entry or some other descriptive text.

           $ pmap
           08048000    420K read/exec         /bin/sh
           080B1000      8K read/write        /bin/sh
           080B3000     28K read/write          [ anon ]
           080BA000     16K read/write/exec     [ heap ]
           ...

     When the ddb(4) output style is selected, the first thing printed is the
     contents of the vm_map structure, followed by the individual map entries.

           $ pmap -d
           MAP 0xcf7cac84: [0x0->0xbfbfe000]
                   #ent=8, sz=34041856, ref=1, version=20, flags=0x41
                   pmap=0xcf44cee0(resident=<unknown>)
            - 0xcfa3a358: 0x8048000->0x80b1000: obj=0xcf45a8e8/0x0, amap=0x0/0
                   submap=F, cow=T, nc=T, prot(max)=5/7, inh=1, wc=0, adv=0
           ...

     The value of the flags field (in hexadecimal) is taken from the include
     file <uvm/uvm_map.h>:

           VM_MAP_PAGEABLE      0x01   entries are pageable
           VM_MAP_INTRSAFE      0x02   interrupt safe map
           VM_MAP_WIREFUTURE    0x04   future mappings are wired
           VM_MAP_BUSY          0x08   map is busy
           VM_MAP_WANTLOCK      0x10   want to write-lock
           VM_MAP_DYING         0x20   map is being destroyed
           VM_MAP_TOPDOWN       0x40   arrange map top-down

     The ``submap'', ``cow'', and ``nc'' fields are true or false, and indi-
     cate whether the map is a submap, whether it is marked for copy on write,
     and whether it needs a copy.  The ``prot'' (or protection) field, along
     with ``max'' (maximum protection allowed) are made up of the following
     flags from <uvm/uvm_extern.h>:

           UVM_PROT_READ        0x01   read allowed
           UVM_PROT_WRITE       0x02   write allowed
           UVM_PROT_EXEC        0x04   execute allowed

     The ``obj'' and ``amap'' fields are pointers to, and offsets into, the
     underlying uvm_object or amap.  The value for resident is always unknown
     because digging such information out of the kernel is beyond the scope of
     this application.

     The two output styles that mirror the contents of the /proc file system
     appear as follows:

           $ pmap -m
           0x8048000 0x80b1000 r-x rwx COW NC 1 0 0
           0x80b1000 0x80b3000 rw- rwx COW NC 1 0 0
           0x80b3000 0x80ba000 rw- rwx COW NNC 1 0 0
           0x80ba000 0x80be000 rwx rwx COW NNC 1 0 0
           ...

           $ pmap -l
           08048000-080b1000 r-xp 00000000 00:00 70173     /bin/sh
           080b1000-080b3000 rw-p 00068000 00:00 70173     /bin/sh
           080b3000-080ba000 rw-p 00000000 00:00 0
           080ba000-080be000 rwxp 00000000 00:00 0
           ...

     Here the protection and maximum protection values are indicated with `r',
     `w', and `x' characters, indicating read permission, write permission,
     and execute permission, respectively.  The ``COW'', ``NC'', and ``NNC''
     values that follow indicate, again, that the map is marked for copy on
     write and either needs or does not need a copy.  It is also possible to
     see the value ``NCOW'' here, which indicates that an entry will not be
     copied.  The three following numbers indicate the inheritance type of the
     map, the wired count of the map, and any advice value assigned via
     madvise(2).

     In the second form, the permissions indicated are followed by a `p' or
     `s' character indicating whether the map entry is private or shared (copy
     on write or not), and the numbers are the offset into the underlying
     object, the device and numbers of the object if it is a file, and the
     path to the file (if available).

     As noted above (see section DESCRIPTION), the ``all'' output format is an
     amalgam of the previous output formats.

           $ pmap -a
           Start    End         Size  Offset   rwxpc  RWX  I/W/A ...
           08048000-080b0fff     420k 00000000 r-xp+ (rwx) 1/0/0 ...
           ...

     In this format, the column labeled ``rwxpc'' contains the permissions for
     the mapping along with the shared/private flag, and a character indicat-
     ing whether the mapping needs to be copied on write (`+') or has already
     been copied (`-') and is followed by a column that indicates the maximum
     permissions for the map entry.  The column labeled ``I/W/A'' indicates
     the inheritance, wired, and advice values for the map entry, as previ-
     ously described.  The pointer value at the end of the output line for
     entries backed by vnodes is the address of the vnode in question.

SEE ALSO
     ls(1), stat(1), madvise(2), mmap(2), kvm(3), ddb(4), mount_procfs(8),
     pmap(9)

HISTORY
     The pmap utility appeared in NetBSD 2.0.

AUTHORS
     The pmap utility and documentation was written by Andrew Brown
     <atatat@NetBSD.org>.

BUGS
     Very little will work unless pmap is reading from the correct kernel in
     order to retrieve the proper symbol information.

     Since processes can change state while pmap is running, some of the
     information printed may be inaccurate.  This is especially important to
     consider when examining the kernel's map, since merely executing pmap
     will cause some of the information to change.

     The pathnames to files backing certain vnodes (such as the text and data
     sections of programs and shared libraries) are extracted from the ker-
     nel's namei cache which is considerably volatile.  If a path is not found
     there in its entirety, as much information as was available will be
     printed.  In most cases, simply running ls(1) or stat(1) with the
     expected path to the file will cause the information to be reentered into
     the cache.

     The Solaris command by the same name has some interesting command line
     flags that would be nice to emulate here.  In particular, the -r option
     that lists a process's reserved addresses, and the -x option that prints
     resident/shared/private mapping details for each entry.

     Some of the output modes can be or are wider than the standard 80 columns
     of a terminal.  Some sort of formatting might be nice.

SECURITY CONSIDERATIONS
     The Solaris command controls access to processes the user does not own
     via the permissions of its /proc file system.  Since pmap uses kvm(3) to
     read the requested data directly from kernel memory, no such limitation
     exists.

     If any of the -A, -E, -M, -N, -S, or -V options are used, any extra priv-
     ileges that pmap has will be dropped.

NetBSD 7.0                     February 6, 2009                     NetBSD 7.0