*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> procmap (1)              
Title
Content
Arch
Section
 

PROCMAP(1)

Contents


NAME    [Toc]    [Back]

     procmap - display process memory map

SYNOPSIS    [Toc]    [Back]

     procmap [-adlmPsv] [-D number] [-M  core]  [-N  system]  [-p
pid] [pid ...]

DESCRIPTION    [Toc]    [Back]

     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.

     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            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:

                  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''.   This is the default output
style.

     -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 `*' 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.  If you do wish to see information about
     procmap and another process as the same  time,  simply  omit
the -p and
     place the extra PID at the end of the command line.

     procmap exits 0 on success, and >0 if an error occurred.

EXAMPLES    [Toc]    [Back]

     While  the  meaning 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,  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 ``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 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 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
           ...

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

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

SEE ALSO    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

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

AUTHORS    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

     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.

OpenBSD     3.6                         August      29,      2002
[ Back ]
 Similar pages
Name OS Title
limits FreeBSD set or display process resource limits
free Linux Display amount of free and used memory in the system
vxmemstat HP-UX display memory statistics for VERITAS Volume Manager
vfork HP-UX spawn new process; share virtual memory
dlook IRIX a tool for showing memory and process placement
vfork FreeBSD spawn new process in a virtual memory efficient way
vfork NetBSD spawn new process in a virtual memory efficient way
plock Tru64 Lock the text and/or data segments of a process in memory
plock IRIX lock into memory or unlock process, text, or data
mlockall HP-UX lock a process virtual address space in memory
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service