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