Unix/Linux Go Back    


NetBSD 6.1.5 - man page for pmap (netbsd section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PMAP(1) 			   BSD General Commands Manual				  PMAP(1)

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 informa-
     tion 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, iden-
		  tifiers 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 identi-
		  fying 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
     pmap exits 0 on success, and >0 if an error occurred.

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 descrip-
     tive 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' char-
     acters, 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 indi-
     cating 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 pro-
     grams and shared libraries) are extracted from the kernel's namei cache which is consider-
     ably 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.

BSD					 February 6, 2009				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:40 PM.