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 information
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
displayed. If other PIDs are given as arguments on the command line,
information 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
similar 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
specified 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
identifying 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 output 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 information is
printed, possibly including device and inode numbers, 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 indicate 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 indicating
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 previously 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 kernel'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 privileges that
pmap has will be
dropped.