381 lines
12 KiB
Groff
381 lines
12 KiB
Groff
.\" $NetBSD: pmap.1,v 1.3 2002/09/17 19:54:28 atatat 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.
|