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