1.\" $NetBSD: pmap.1,v 1.17 2010/05/14 17:31:26 joerg 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.Nm 206exits 0 on success, and \*[Gt]0 if an error occurred. 207.Sh EXAMPLES 208While the meaning of most of the output is self-evident, some pieces of 209it may appear to be a little inscrutable. 210.Pp 211Here is a portion of the default output from 212.Nm 213being run at an 214.Xr sh 1 215prompt showing the starting address of the map entry, the size of the 216map entry, the current protection level of the map entry, and either 217the name of the file backing the entry or some other descriptive text. 218.Bd -literal -offset indent 219$ pmap 22008048000 420K read/exec /bin/sh 221080B1000 8K read/write /bin/sh 222080B3000 28K read/write [ anon ] 223080BA000 16K read/write/exec [ heap ] 224\&... 225.Ed 226.Pp 227When the 228.Xr ddb 4 229output style is selected, the first thing printed is the contents of 230the vm_map structure, followed by the individual map entries. 231.Bd -literal -offset indent 232$ pmap -d 233MAP 0xcf7cac84: [0x0-\*[Gt]0xbfbfe000] 234 #ent=8, sz=34041856, ref=1, version=20, flags=0x41 235 pmap=0xcf44cee0(resident=\*[Lt]unknown\*[Gt]) 236 - 0xcfa3a358: 0x8048000-\*[Gt]0x80b1000: obj=0xcf45a8e8/0x0, amap=0x0/0 237 submap=F, cow=T, nc=T, prot(max)=5/7, inh=1, wc=0, adv=0 238\&... 239.Ed 240.Pp 241The value of the flags field (in hexadecimal) is taken from 242the include file 243.In uvm/uvm_map.h : 244.Bl -column VM_MAP_WIREFUTURE VM_MAP_WIREFUTURE -offset indent 245.It Dv "VM_MAP_PAGEABLE" Ta No "0x01 entries are pageable" 246.It Dv "VM_MAP_INTRSAFE" Ta No "0x02 interrupt safe map" 247.It Dv "VM_MAP_WIREFUTURE" Ta No "0x04 future mappings are wired" 248.It Dv "VM_MAP_BUSY" Ta No "0x08 map is busy" 249.It Dv "VM_MAP_WANTLOCK" Ta No "0x10 want to write-lock" 250.It Dv "VM_MAP_DYING" Ta No "0x20 map is being destroyed" 251.It Dv "VM_MAP_TOPDOWN" Ta No "0x40 arrange map top-down" 252.El 253.Pp 254The 255.Dq submap , 256.Dq cow , 257and 258.Dq nc 259fields are true or false, and indicate whether the map is a submap, 260whether it is marked for copy on write, and whether it needs a copy. 261The 262.Dq prot 263\&(or protection) field, along with 264.Dq max 265\&(maximum protection allowed) are made up of the following flags from 266.In uvm/uvm_extern.h : 267.\" this column width specifically chosen so that all the header file 268.\" excerpts appear to line up cleanly 269.Bl -column VM_MAP_WIREFUTURE VM_MAP_WIREFUTURE -offset indent 270.It Dv "UVM_PROT_READ" Ta No "0x01 read allowed" 271.It Dv "UVM_PROT_WRITE" Ta No "0x02 write allowed" 272.It Dv "UVM_PROT_EXEC" Ta No "0x04 execute allowed" 273.El 274.Pp 275The 276.Dq obj 277and 278.Dq amap 279fields are pointers to, and offsets into, the underlying uvm_object or 280amap. 281The value for resident is always unknown because digging such 282information out of the kernel is beyond the scope of this application. 283.Pp 284The two output styles that mirror the contents of the 285.Pa /proc 286file system 287appear as follows: 288.Bd -literal -offset indent 289$ pmap -m 2900x8048000 0x80b1000 r-x rwx COW NC 1 0 0 2910x80b1000 0x80b3000 rw- rwx COW NC 1 0 0 2920x80b3000 0x80ba000 rw- rwx COW NNC 1 0 0 2930x80ba000 0x80be000 rwx rwx COW NNC 1 0 0 294\&... 295 296$ pmap -l 29708048000-080b1000 r-xp 00000000 00:00 70173 /bin/sh 298080b1000-080b3000 rw-p 00068000 00:00 70173 /bin/sh 299080b3000-080ba000 rw-p 00000000 00:00 0 300080ba000-080be000 rwxp 00000000 00:00 0 301\&... 302.Ed 303.Pp 304Here the protection and maximum protection values are indicated with 305.Sq r , 306.Sq w , 307and 308.Sq x 309characters, indicating read permission, write permission, and execute 310permission, respectively. 311The 312.Dq COW , 313.Dq NC , 314and 315.Dq NNC 316values that follow indicate, again, that the map is marked for copy on 317write and either needs or does not need a copy. 318It is also possible 319to see the value 320.Dq NCOW 321here, which indicates that an entry will not be copied. 322The three 323following numbers indicate the inheritance type of the map, the wired 324count of the map, and any advice value assigned via 325.Xr madvise 2 . 326.Pp 327In the second form, the permissions indicated are followed by a 328.Sq p 329or 330.Sq s 331character indicating whether the map entry is private or shared (copy 332on write or not), and the numbers are the offset into the underlying 333object, the device and numbers of the object if it is a file, and the 334path to the file (if available). 335.Pp 336As noted above (see section 337.Sx DESCRIPTION ) , 338the 339.Dq all 340output format is an amalgam of the previous output formats. 341.Bd -literal -offset indent 342$ pmap -a 343Start End Size Offset rwxpc RWX I/W/A ... 34408048000-080b0fff 420k 00000000 r-xp+ (rwx) 1/0/0 ... 345\&... 346.Ed 347.Pp 348In this format, the column labeled 349.Dq rwxpc 350contains the permissions for the mapping along with the shared/private 351flag, and a character indicating whether the mapping needs to be 352copied on write 353.Pq Sq \&+ 354or has already been copied 355.Pq Sq \&- 356and is followed by a column that indicates the maximum permissions for 357the map entry. 358The column labeled 359.Dq I/W/A 360indicates the inheritance, wired, and advice values for the map entry, 361as previously described. 362The pointer value at the end of the output line for entries backed by 363vnodes is the address of the vnode in question. 364.Sh SEE ALSO 365.Xr ls 1 , 366.Xr stat 1 , 367.Xr madvise 2 , 368.Xr mmap 2 , 369.Xr kvm 3 , 370.Xr ddb 4 , 371.Xr mount_procfs 8 , 372.Xr pmap 9 373.Sh HISTORY 374The 375.Nm 376utility appeared in 377.Nx 2.0 . 378.Sh AUTHORS 379The 380.Nm 381utility and documentation was written by 382.An Andrew Brown 383.Aq atatat@NetBSD.org . 384.Sh BUGS 385Very little will work unless 386.Nm 387is reading from the correct kernel in order to retrieve the 388proper symbol information. 389.Pp 390Since processes can change state while 391.Nm 392is running, some of the information printed may be inaccurate. 393This 394is especially important to consider when examining the kernel's map, 395since merely executing 396.Nm 397will cause some of the information to change. 398.Pp 399The pathnames to files backing certain vnodes (such as the text and 400data sections of programs and shared libraries) are extracted from the 401kernel's namei cache which is considerably volatile. 402If a path is not 403found there in its entirety, as much information as was available 404will be printed. 405In most cases, simply running 406.Xr ls 1 407or 408.Xr stat 1 409with the expected path to the file will cause the information to be 410reentered into the cache. 411.Pp 412The Solaris command by the same name has some interesting command line 413flags that would be nice to emulate here. 414In particular, the 415.Fl r 416option that lists a process's reserved addresses, and the 417.Fl x 418option that prints resident/shared/private mapping details for each 419entry. 420.Pp 421Some of the output modes can be or are wider than the standard 80 422columns of a terminal. 423Some sort of formatting might be nice. 424.Sh SECURITY CONSIDERATIONS 425The Solaris command controls access to processes the user does not own 426via the permissions of its 427.Pa /proc 428file system. 429Since 430.Nm 431uses 432.Xr kvm 3 433to read the requested data directly from kernel memory, no such 434limitation exists. 435.Pp 436If any of the 437.Fl A , 438.Fl E , 439.Fl M , 440.Fl N , 441.Fl S , 442or 443.Fl V 444options are used, any extra privileges that 445.Nm 446has will be dropped. 447