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