OpenBSD manual page server

NAME

procmap — display process memory map

SYNOPSIS

DESCRIPTION

The procmap 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. The various output formats are explained in greater detail below.

procmap requires the ability to open /dev/kmem which may be restricted based upon the value of the kern.allowkmem sysctl(8).

By default, procmap 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

Print more detailed information on anonymous map usage.

-a

Display “all” information from the process's memory map. This output mode is an amalgam of the contents of the Solaris, Linux, and OpenBSD style output modes, and attempts to maximize information displayed. This is the default output style.

-D number

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

1

dump the process's vmspace structure

2

dump the process's vm_map structure

4

dump the vm_map.header structure

8

dump each vm_map_entry in its entirety

16

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_entry fields will be printed.

-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 running kernel.

-P

Causes procmap to print information about itself.

-p pid

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

-s

The Solaris style output format, modeled after the Solaris command “pmap”.

-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 used with -a, a line marked with ‘*’ 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.

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

OUTPUT FORMAT

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

Here a portion of the default output from procmap being run at a 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.

# procmap
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.

# procmap -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, stack=F, immutable=F, 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	ro: entries are pageable
VM_MAP_INTRSAFE		0x02	ro: interrupt safe map
VM_MAP_WIREFUTURE	0x04	rw: wire future mappings
VM_MAP_BUSY		0x08	rw: map is busy
VM_MAP_WANTLOCK		0x10	rw: want to write-lock

The “prot” (or protection) field, along with “max” (maximum protection allowed), are made up of the following flags from <uvm/uvm_extern.h>:

PROT_READ	0x01	read allowed
PROT_WRITE	0x02	write allowed
PROT_EXEC	0x04	execute allowed

The “obj” and “amap” fields are pointers to, and offsets into, the underlying uvm_object or vm_amap object. 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:

# procmap -m
0x8048000 0x80b1000 r-x--I rwx COW NC 1 0 0
0xdecf000 0xd018000 r-x--I rwx COW NC 1 0 0
0x80b1000 0x80b3000 rw---I rwx COW NC 1 0 0
0x80b3000 0x80ba000 rw---I rwx COW NNC 1 0 0
0x80ba000 0x80be000 rwx--I rwx COW NNC 1 0 0
...

# procmap -l
0x08048000	0x080b1000	r-x--Ip 00000000 00:00 70173     /bin/sh
0x080b1000	0x080b3000	rw---Ip 00068000 00:00 70173     /bin/sh
0x080b3000	0x080ba000	rw---Ip 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 remaining fields of this column are described below. 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, the “all” output format is an amalgam of the previous output formats.

# procmap -a
Start    End         Size  Offset   rwxSeIpc  RWX  I/W/A ...
08048000-080b0fff     420k 00000000 r-x---p+ (rwx) 1/0/0 ...
...

In this format the column labeled “rwxSeIpc” comprises:

It is followed by the RWX column, which 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.

EXIT STATUS

The procmap utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

ls(1), madvise(2), mmap(2), kvm(3), ddb(4), namei(9), vnode(9)

HISTORY

The procmap utility first appeared in OpenBSD 3.5. It was derived from the NetBSD utility known as “pmap”.

AUTHORS

The procmap utility and documentation was written by Andrew Brown <atatat@netbsd.org>.

BUGS

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

Since processes can change state while procmap 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 procmap 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) with the expected path to the file will cause the information to be reentered into the cache.

The Solaris version (“pmap”) 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.