usr.bin/pmap/pmap.1

.\"	$NetBSD: pmap.1,v 1.4 2002/09/30 11:09:08 grant Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Andrew Brown.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 29, 2002
.Dt PMAP 1
.Os
.Sh NAME
.Nm pmap
.Nd display process memory map
.Sh SYNOPSIS
.Nm
.Op Fl adlmPRsv
.Op Fl D Ar number
.Op Fl M Ar core
.Op Fl N Ar system
.Op Fl p Ar pid
.Op Ar pid ...
.Sh DESCRIPTION
The
.Nm
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.
.Pp
By default,
.Nm
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.
.Pp
The options are as follows:
.Bl -tag -width XXXnumberXX
.It Fl D Ar number
Enable various debug facilities.
The
.Ar number
is a bit mask of the values:
.Pp
.Bl -tag -width flag -compact
.It Cm 1
dump the process's vmspace structure
.It Cm 2
dump the process's vm_map structure
.It Cm 4
dump the vm_map.header structure
.It Cm 8
dump each vm_map_entry in its entirety
.It Cm 16
dump the namei cache as it is traversed
.El
.It Fl M Ar core
Extract values associated with the name list from the specified core
instead of the default
.Pa /dev/kmem .
.It Fl N Ar system
Extract the name list from the specified system instead of the default
.Pa /netbsd .
.It Fl P
Causes
.Nm
to print information about itself.
.It Fl a
Display
.Dq all
information from the process's memory map.
This output
mode is an amalgam of the contents of the Solaris, Linux, and
.Nx
style output modes.
.It Fl d
Dumps the vm_map and vm_map_entry structures in a style similar to
that of
.Xr ddb 4 .
When combined with the
.Fl v
option, the device number, inode number, name, vnode addresses, or
other identifying information from the vm_map_entries will be printed.
.It Fl l
Dumps information in a format like the contents of the maps
pseudo-file under the
.Pa /proc
file system which was, in turn, modeled after the similarly named entry
in the Linux
.Pa /proc
file system.
When combined with the
.Fl v
option, identifiers for all entries are printed.
.It Fl m
Dumps information in the same format as the map pseudo-file of the
.Pa /proc
file system.
When the
.Fl v
option is also given, device number, inode number, and filename
or other identifying information is printed.
.It Fl p Ar pid
Tells
.Nm
to print information about the given process.
If
.Fl p Ar pid
occurs last on the command line, the
.Fl p
is optional.
.It Fl R
Recurse into submaps.
In some cases, a vm_map_entry in the kernel
will point to a submap.
Using this flag tells
.Nm
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.
.It Fl s
The Solaris style output format, modeled after the Solaris command of
the same name.
This is the default output style.
.It Fl v
Verbose output.
When used with
.Fl d ,
.Fl l ,
or
.Fl m ,
more information is printed, possibly including device and inode
numbers, file path names, or other identifying information.
.El
.Pp
The
.Fl P
and
.Fl 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
.Nm
and another process as the same time, simply omit the
.Fl p
and place the extra pid at the end of the command line.
.Sh EXIT STATUS
.Nm
exits 0 on success, and \*[Gt]0 if an error occurred.
.Sh EXAMPLES
While the meaning most of the output is self evident, some pieces of
it may appear to be a little inscrutable.
.Pp
Here a portion of the default output from pmap being run at an
.Xr sh 1
prompt shows 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.
.Bd -literal -offset indent
$ pmap
08048000    420K read/exec         /bin/sh
080B1000      8K read/write        /bin/sh
080B3000     28K read/write          [ anon ]
080BA000     16K read/write/exec     [ heap ]
\&...
.Ed
.Pp
When the
.Xr ddb 4
output style is selected, the first thing printed is the contents of
the vm_map structure, followed by the individual map entries.
.Bd -literal -offset indent
$ pmap -d
MAP 0xcf7cac84: [0x0->0xbfbfe000]
        #ent=8, sz=34041856, ref=1, version=20, flags=0x21
        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
\&...
.Ed
.Pp
The value of the flags field (in hexadecimal) is taken from
the include file
.Aq Pa uvm/uvm_map.h :
.Bl -column VM_MAP_WIREFUTURE VM_MAP_WIREFUTURE -offset indent
.It Dv "VM_MAP_PAGEABLE"   Ta No "0x01   entries are pageable"
.It Dv "VM_MAP_INTRSAFE"   Ta No "0x02   interrupt safe map"
.It Dv "VM_MAP_WIREFUTURE" Ta No "0x04   future mappings are wired
.It Dv "VM_MAP_BUSY"       Ta No "0x08   map is busy
.It Dv "VM_MAP_WANTLOCK"   Ta No "0x10   want to write-lock
.El
.Pp
The
.Dq Tn submap ,
.Dq Tn cow ,
and
.Dq Tn 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
.Dq Tn prot
\&(or protection) field, along with
.Dq Tn max
\&(maximum protection allowed) are made up of the following flags from
.Aq Pa uvm/uvm_extern.h :
.\" this column width specifically chosen so that all the header file
.\" excerpts appear to line up cleanly
.Bl -column VM_MAP_WIREFUTURE VM_MAP_WIREFUTURE -offset indent
.It Dv "UVM_PROT_READ"  Ta No "0x01   read allowed"
.It Dv "UVM_PROT_WRITE" Ta No "0x02   write allowed"
.It Dv "UVM_PROT_EXEC"  Ta No "0x04   execute allowed"
.El
.Pp
The
.Dq Tn obj
and
.Dq Tn 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.
.Pp
The two output styles that mirror the contents of the
.Pa /proc
file system
appear as follows:
.Bd -literal -offset indent
$ 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
\&...
.Ed
.Pp
Here the protection and maximum protection values are indicated with
.Dq Tn r ,
.Dq Tn w ,
and
.Dq Tn x
characters, indicating read permission, write permission, and execute
permission, respectively.
The
.Dq Tn COW ,
.Dq Tn NC ,
and
.Dq Tn 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
.Dq Tn 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
.Xr madvise 2 .
.Pp
In the second form, the permissions indicated are followed by a
.Dq Tn p
or
.Dq Tn s
character indicated 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).
.Pp
As noted above (see section
.Sx DESCRIPTION ) ,
the
.Dq Tn all
output format is an amalgam of the previous output formats.
.Bd -literal -offset indent
$ pmap -a
Start    End         Size  Offset   rwxpc  RWX  I/W/A ...
08048000-080b0fff     420k 00000000 r-xp+ (rwx) 1/0/0 ...
\&...
.Ed
.Pp
In this format, the column labeled
.Dq Tn 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
.Pq Dq \&+
or has already been copied
.Pq Dq \&-
and is followed by a column that indicates the maximum permissions for
the map entry.
The column labeled
.Dq Tn I/W/A
indicates the inheritance, wired, and advice values for the map entry,
as previously described.
.Sh SEE ALSO
.Xr ls 1 ,
.Xr stat 1 ,
.Xr madvise 2 ,
.Xr mmap 2 ,
.Xr kvm 3 ,
.Xr ddb 4 ,
.Xr mount_procfs 8
.Sh HISTORY
The
.Nm
utility appeared in
.Nx 1.7 .
.Sh AUTHORS
The
.Nm
utility and documentation was written by Andrew Brown
.Aq atatat@netbsd.org .
.Sh BUGS
Very little will work unless
.Nm
is reading from the correct kernel in order to retrieve the
proper symbol information.
.Pp
Since processes can change state while
.Nm
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
.Nm
will cause some of the information to change.
.Pp
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
.Xr ls 1
or
.Xr stat 1
with the expected path to the file will cause the information to be
reentered into the cache.
.Pp
The Solaris command by the same name has some interesting command line
flags that would be nice to emulate here.
In particular, the
.Fl r
option that lists a process's reserved addresses, and the
.Fl x
option that prints resident/shared/private mapping details for each
entry.
.Pp
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.
.Sh SECURITY CONSIDERATIONS
The Solaris command controls access to processes the user does not own
via the permissions of its
.Pa /proc
file system.
Since
.Nm
uses
.Xr kvm 3
to read the requested data directly from kernel memory, no such
limitation exists.