1.\" $NetBSD: pmap.1,v 1.18 2014/04/13 01:45:34 snj Exp $ 2.\" 3.\" Copyright (c) 2002, 2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Brown. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 6, 2009 31.Dt PMAP 1 32.Os 33.Sh NAME 34.Nm pmap 35.Nd display process memory map 36.Sh SYNOPSIS 37.Nm 38.Op Fl adlmPRsv 39.Op Fl A Ar address 40.Op Fl D Ar number 41.Op Fl E Ar address 42.Op Fl M Ar core 43.Op Fl N Ar system 44.Op Fl p Ar pid 45.Op Fl S Ar address 46.Op Fl V Ar address 47.Op Ar pid ... 48.Sh DESCRIPTION 49The 50.Nm 51utility lists the virtual memory mappings underlying the given 52process. 53The start address of each entry is always given, and, 54depending on the options given, other information such as the end 55address, the underlying file's device and inode numbers, and various 56protection information will be displayed, along with the path to the 57file, if such data is available. 58.Pp 59By default, 60.Nm 61displays information for its parent process, so that when run from a 62shell prompt, the shell's memory information is displayed. 63If other 64PIDs are given as arguments on the command line, information for those 65processes will be printed also. 66If the special PID of 0 is given, 67then information for the kernel's memory map is printed. 68.Pp 69The options are as follows: 70.Bl -tag -width XXXnumberXX 71.It Fl A Ar address 72Dumps the vm_amap structure found at 73.Ar address . 74.It Fl a 75Display 76.Dq all 77information from the process's memory map. 78This output 79mode is an amalgam of the contents of the Solaris, Linux, and 80.Nx 81style output modes. 82.It Fl D Ar number 83Enable various debug facilities. 84The 85.Ar number 86is a bit mask of the values: 87.Pp 88.Bl -tag -width 0x1000 -compact 89.It Cm 0x01 90dump the process's vmspace structure 91.It Cm 0x02 92dump the process's vm_map structure 93.It Cm 0x04 94dump the vm_map.header structure 95.It Cm 0x08 96dump each vm_map_entry in its entirety 97.It Cm 0x10 98dump the vm_amap structure attached to the vm_map_entry, if applicable 99.It Cm 0x20 100dump the vm_amap slot data, if present (requires 0x10) 101.It Cm 0x40 102dump the vm_anon data from the am_anon array, if present (requires 0x20) 103.It Cm 0x1000 104dump the namei cache as it is traversed 105.El 106.It Fl d 107Dumps the vm_map and vm_map_entry structures in a style similar to 108that of 109.Xr ddb 4 . 110When combined with the 111.Fl v 112option, the device number, inode number, name, vnode addresses, or 113other identifying information from the vm_map_entries will be printed. 114.It Fl E Ar address 115Dumps the vm_map_entry structure found at 116.Ar address . 117.It Fl l 118Dumps information in a format like the contents of the maps 119pseudo-file under the 120.Pa /proc 121file system which was, in turn, modeled after the similarly named entry 122in the Linux 123.Pa /proc 124file system. 125When combined with the 126.Fl v 127option, identifiers for all entries are printed. 128.It Fl M Ar core 129Extract values associated with the name list from the specified core 130instead of the default 131.Pa /dev/kmem . 132.It Fl m 133Dumps information in the same format as the map pseudo-file of the 134.Pa /proc 135file system. 136When the 137.Fl v 138option is also given, device number, inode number, and filename 139or other identifying information is printed. 140.It Fl N Ar system 141Extract the name list from the specified system instead of the default 142.Pa /netbsd . 143.It Fl P 144Causes 145.Nm 146to print information about itself. 147.It Fl p Ar pid 148Tells 149.Nm 150to print information about the given process. 151If 152.Fl p Ar pid 153occurs last on the command line, the 154.Fl p 155is optional. 156.It Fl R 157Recurse into submaps. 158In some cases, a vm_map_entry in the kernel 159will point to a submap. 160Using this flag tells 161.Nm 162to print the entries of the submap as well. 163The submap output is 164indented, and does not affect any total printed at the bottom of the 165output. 166.It Fl S Ar address 167Dumps the vmspace structure found at 168.Ar address . 169.It Fl s 170The Solaris style output format, modeled after the Solaris command of 171the same name. 172This is the default output style. 173.It Fl V Ar address 174Dumps the vm_map structure found at 175.Ar address . 176Note that if you print the vm_map of a process, there may not be a way 177to properly determine which map entries are related to the stack. 178.It Fl v 179Verbose output. 180When used with 181.Fl d , 182.Fl l , 183or 184.Fl m , 185more information is printed, possibly including device and inode 186numbers, file path names, or other identifying information. 187If specified more than once, a small note will be printed in between 188two entries that are not adjacent, making the visual identification of 189spaces in the process's map easier to see, that indicates the number 190of pages and the amount of memory space that is skipped. 191.El 192.Pp 193The 194.Fl P 195and 196.Fl p 197options override each other, so the last one to appear on the command 198line takes effect. 199If you do wish to see information about 200.Nm 201and another process as the same time, simply omit the 202.Fl p 203and place the extra PID at the end of the command line. 204.Sh EXIT STATUS 205.Ex -std 206.Sh EXAMPLES 207While the meaning of most of the output is self-evident, some pieces of 208it may appear to be a little inscrutable. 209.Pp 210Here is a portion of the default output from 211.Nm 212being run at an 213.Xr sh 1 214prompt showing the starting address of the map entry, the size of the 215map entry, the current protection level of the map entry, and either 216the name of the file backing the entry or some other descriptive text. 217.Bd -literal -offset indent 218$ pmap 21908048000 420K read/exec /bin/sh 220080B1000 8K read/write /bin/sh 221080B3000 28K read/write [ anon ] 222080BA000 16K read/write/exec [ heap ] 223\&... 224.Ed 225.Pp 226When the 227.Xr ddb 4 228output style is selected, the first thing printed is the contents of 229the vm_map structure, followed by the individual map entries. 230.Bd -literal -offset indent 231$ pmap -d 232MAP 0xcf7cac84: [0x0-\*[Gt]0xbfbfe000] 233 #ent=8, sz=34041856, ref=1, version=20, flags=0x41 234 pmap=0xcf44cee0(resident=\*[Lt]unknown\*[Gt]) 235 - 0xcfa3a358: 0x8048000-\*[Gt]0x80b1000: obj=0xcf45a8e8/0x0, amap=0x0/0 236 submap=F, cow=T, nc=T, prot(max)=5/7, inh=1, wc=0, adv=0 237\&... 238.Ed 239.Pp 240The value of the flags field (in hexadecimal) is taken from 241the include file 242.In uvm/uvm_map.h : 243.Bl -column VM_MAP_WIREFUTURE VM_MAP_WIREFUTURE -offset indent 244.It Dv "VM_MAP_PAGEABLE" Ta No "0x01 entries are pageable" 245.It Dv "VM_MAP_INTRSAFE" Ta No "0x02 interrupt safe map" 246.It Dv "VM_MAP_WIREFUTURE" Ta No "0x04 future mappings are wired" 247.It Dv "VM_MAP_BUSY" Ta No "0x08 map is busy" 248.It Dv "VM_MAP_WANTLOCK" Ta No "0x10 want to write-lock" 249.It Dv "VM_MAP_DYING" Ta No "0x20 map is being destroyed" 250.It Dv "VM_MAP_TOPDOWN" Ta No "0x40 arrange map top-down" 251.El 252.Pp 253The 254.Dq submap , 255.Dq cow , 256and 257.Dq nc 258fields are true or false, and indicate whether the map is a submap, 259whether it is marked for copy on write, and whether it needs a copy. 260The 261.Dq prot 262\&(or protection) field, along with 263.Dq max 264\&(maximum protection allowed) are made up of the following flags from 265.In uvm/uvm_extern.h : 266.\" this column width specifically chosen so that all the header file 267.\" excerpts appear to line up cleanly 268.Bl -column VM_MAP_WIREFUTURE VM_MAP_WIREFUTURE -offset indent 269.It Dv "UVM_PROT_READ" Ta No "0x01 read allowed" 270.It Dv "UVM_PROT_WRITE" Ta No "0x02 write allowed" 271.It Dv "UVM_PROT_EXEC" Ta No "0x04 execute allowed" 272.El 273.Pp 274The 275.Dq obj 276and 277.Dq amap 278fields are pointers to, and offsets into, the underlying uvm_object or 279amap. 280The value for resident is always unknown because digging such 281information out of the kernel is beyond the scope of this application. 282.Pp 283The two output styles that mirror the contents of the 284.Pa /proc 285file system 286appear as follows: 287.Bd -literal -offset indent 288$ pmap -m 2890x8048000 0x80b1000 r-x rwx COW NC 1 0 0 2900x80b1000 0x80b3000 rw- rwx COW NC 1 0 0 2910x80b3000 0x80ba000 rw- rwx COW NNC 1 0 0 2920x80ba000 0x80be000 rwx rwx COW NNC 1 0 0 293\&... 294 295$ pmap -l 29608048000-080b1000 r-xp 00000000 00:00 70173 /bin/sh 297080b1000-080b3000 rw-p 00068000 00:00 70173 /bin/sh 298080b3000-080ba000 rw-p 00000000 00:00 0 299080ba000-080be000 rwxp 00000000 00:00 0 300\&... 301.Ed 302.Pp 303Here the protection and maximum protection values are indicated with 304.Sq r , 305.Sq w , 306and 307.Sq x 308characters, indicating read permission, write permission, and execute 309permission, respectively. 310The 311.Dq COW , 312.Dq NC , 313and 314.Dq NNC 315values that follow indicate, again, that the map is marked for copy on 316write and either needs or does not need a copy. 317It is also possible 318to see the value 319.Dq NCOW 320here, which indicates that an entry will not be copied. 321The three 322following numbers indicate the inheritance type of the map, the wired 323count of the map, and any advice value assigned via 324.Xr madvise 2 . 325.Pp 326In the second form, the permissions indicated are followed by a 327.Sq p 328or 329.Sq s 330character indicating whether the map entry is private or shared (copy 331on write or not), and the numbers are the offset into the underlying 332object, the device and numbers of the object if it is a file, and the 333path to the file (if available). 334.Pp 335As noted above (see section 336.Sx DESCRIPTION ) , 337the 338.Dq all 339output format is an amalgam of the previous output formats. 340.Bd -literal -offset indent 341$ pmap -a 342Start End Size Offset rwxpc RWX I/W/A ... 34308048000-080b0fff 420k 00000000 r-xp+ (rwx) 1/0/0 ... 344\&... 345.Ed 346.Pp 347In this format, the column labeled 348.Dq rwxpc 349contains the permissions for the mapping along with the shared/private 350flag, and a character indicating whether the mapping needs to be 351copied on write 352.Pq Sq \&+ 353or has already been copied 354.Pq Sq \&- 355and is followed by a column that indicates the maximum permissions for 356the map entry. 357The column labeled 358.Dq I/W/A 359indicates the inheritance, wired, and advice values for the map entry, 360as previously described. 361The pointer value at the end of the output line for entries backed by 362vnodes is the address of the vnode in question. 363.Sh SEE ALSO 364.Xr ls 1 , 365.Xr stat 1 , 366.Xr madvise 2 , 367.Xr mmap 2 , 368.Xr kvm 3 , 369.Xr ddb 4 , 370.Xr mount_procfs 8 , 371.Xr pmap 9 372.Sh HISTORY 373The 374.Nm 375utility appeared in 376.Nx 2.0 . 377.Sh AUTHORS 378The 379.Nm 380utility and documentation was written by 381.An Andrew Brown 382.Aq atatat@NetBSD.org . 383.Sh BUGS 384Very little will work unless 385.Nm 386is reading from the correct kernel in order to retrieve the 387proper symbol information. 388.Pp 389Since processes can change state while 390.Nm 391is running, some of the information printed may be inaccurate. 392This 393is especially important to consider when examining the kernel's map, 394since merely executing 395.Nm 396will cause some of the information to change. 397.Pp 398The pathnames to files backing certain vnodes (such as the text and 399data sections of programs and shared libraries) are extracted from the 400kernel's namei cache which is considerably volatile. 401If a path is not 402found there in its entirety, as much information as was available 403will be printed. 404In most cases, simply running 405.Xr ls 1 406or 407.Xr stat 1 408with the expected path to the file will cause the information to be 409reentered into the cache. 410.Pp 411The Solaris command by the same name has some interesting command line 412flags that would be nice to emulate here. 413In particular, the 414.Fl r 415option that lists a process's reserved addresses, and the 416.Fl x 417option that prints resident/shared/private mapping details for each 418entry. 419.Pp 420Some of the output modes can be or are wider than the standard 80 421columns of a terminal. 422Some sort of formatting might be nice. 423.Sh SECURITY CONSIDERATIONS 424The Solaris command controls access to processes the user does not own 425via the permissions of its 426.Pa /proc 427file system. 428Since 429.Nm 430uses 431.Xr kvm 3 432to read the requested data directly from kernel memory, no such 433limitation exists. 434.Pp 435If any of the 436.Fl A , 437.Fl E , 438.Fl M , 439.Fl N , 440.Fl S , 441or 442.Fl V 443options are used, any extra privileges that 444.Nm 445has will be dropped. 446