1.\" $OpenBSD: procmap.1,v 1.17 2014/02/13 21:17:13 tedu 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: February 13 2014 $ 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 56By default, 57.Nm 58displays information for its parent process, so that when run from a 59shell prompt, the shell's memory information is displayed. 60If other 61PIDs are given as arguments on the command line, information for those 62processes will be printed also. 63If the special PID of 0 is given, 64then information for the kernel's memory map is printed. 65.Pp 66The options are as follows: 67.Bl -tag -width XXXnumberXX 68.It Fl A 69Print more detailed information on anonymous map usage. 70.It Fl a 71Display 72.Dq all 73information from the process's memory map. 74This output 75mode is an amalgam of the contents of the Solaris, Linux, and 76.Ox 77style output modes. 78.It Fl D Ar number 79Enable various debug facilities. 80The 81.Ar number 82is a bit mask of the values: 83.Pp 84.Bl -tag -width flag -compact 85.It Cm 1 86dump the process's vmspace structure 87.It Cm 2 88dump the process's vm_map structure 89.It Cm 4 90dump the vm_map.header structure 91.It Cm 8 92dump each vm_map_entry in its entirety 93.El 94.It Fl d 95Dumps the vm_map and vm_map_entry structures in a style similar to 96that of 97.Xr ddb 4 . 98When combined with the 99.Fl v 100option, the device number, inode number, name, vnode addresses, or 101other identifying information from the vm_map_entry fields will be 102printed. 103.It Fl l 104Dumps information in a format like the contents of the maps 105pseudo-file under the 106.Pa /proc 107file system which was, in turn, modeled after the similarly named entry 108in the Linux 109.Pa /proc 110file system. 111When combined with the 112.Fl v 113option, identifiers for all entries are printed. 114.It Fl M Ar core 115Extract values associated with the name list from the specified core 116instead of the default 117.Pa /dev/kmem . 118.It Fl m 119Dumps information in the same format as the map pseudo-file of the 120.Pa /proc 121file system. 122When the 123.Fl v 124option is also given, device number, inode number, and filename 125or other identifying information is printed. 126.It Fl N Ar system 127Extract the name list from the specified system instead of the 128running kernel. 129.It Fl P 130Causes 131.Nm 132to print information about itself. 133.It Fl p Ar pid 134Tells 135.Nm 136to print information about the given process. 137If 138.Fl p Ar pid 139occurs last on the command line, the 140.Fl p 141is optional. 142.\" .It Fl R 143.\" Recurse into submaps. 144.\" In some cases, a vm_map_entry in the kernel 145.\" will point to a submap. 146.\" Using this flag tells 147.\" .Nm 148.\" to print the entries of the submap as well. 149.\" The submap output is 150.\" indented, and does not affect any total printed at the bottom of the 151.\" output. 152.It Fl s 153The Solaris style output format, modeled after the Solaris command 154.Dq pmap . 155This is the default output style. 156.It Fl v 157Verbose output. 158When used with 159.Fl d , 160.Fl l , 161or 162.Fl m , 163more information is printed, possibly including device and inode 164numbers, file path names, or other identifying information. 165If specified more than once, a 166.Sq * 167will be printed in between two 168entries that are not adjacent, making the visual identification of 169spaces in the process's map easier to see. 170.El 171.Pp 172The 173.Fl P 174and 175.Fl p 176options override each other, so the last one to appear on the command 177line takes effect. 178If you do wish to see information about 179.Nm 180and another process as the same time, simply omit the 181.Fl p 182and place the extra PID at the end of the command line. 183.Sh EXIT STATUS 184.Ex -std procmap 185.Sh EXAMPLES 186While the meaning most of the output is self-evident, some pieces of 187it may appear to be a little inscrutable. 188.Pp 189Here a portion of the default output from 190.Nm 191being run at a 192.Xr sh 1 193prompt shows the starting address of the map entry, the size of the 194map entry, the current protection level of the map entry, and either 195the name of the file backing the entry or some other descriptive text. 196.Bd -literal -offset indent 197$ procmap 19808048000 420K read/exec /bin/sh 199080B1000 8K read/write /bin/sh 200080B3000 28K read/write [ anon ] 201080BA000 16K read/write/exec [ heap ] 202\&... 203.Ed 204.Pp 205When the 206.Xr ddb 4 207output style is selected, the first thing printed is the contents of 208the vm_map structure, followed by the individual map entries. 209.Bd -literal -offset indent 210$ procmap -d 211MAP 0xcf7cac84: [0x0-\*(Gt0xbfbfe000] 212 #ent=8, sz=34041856, ref=1, version=20, flags=0x21 213 pmap=0xcf44cee0(resident=\*(Ltunknown\*(Gt) 214 - 0xcfa3a358: 0x8048000-\*(Gt0x80b1000: obj=0xcf45a8e8/0x0, amap=0x0/0 215 submap=F, cow=T, nc=T, prot(max)=5/7, inh=1, wc=0, adv=0 216\&... 217.Ed 218.Pp 219The value of the flags field (in hexadecimal) is taken from 220the include file 221.In uvm/uvm_map.h : 222.Bd -literal -offset indent 223VM_MAP_PAGEABLE 0x01 ro: entries are pageable 224VM_MAP_INTRSAFE 0x02 ro: interrupt safe map 225VM_MAP_WIREFUTURE 0x04 rw: wire future mappings 226VM_MAP_BUSY 0x08 rw: map is busy 227VM_MAP_WANTLOCK 0x10 rw: want to write-lock 228.Ed 229.Pp 230The 231.Dq submap , 232.Dq cow , 233and 234.Dq nc 235fields are true or false, and indicate whether the map is a submap, 236whether it is marked for copy on write, and whether it needs a copy. 237The 238.Dq prot 239(or protection) field, along with 240.Dq max 241(maximum protection allowed) are made up of the following flags from 242.In uvm/uvm_extern.h : 243.\" this column width specifically chosen so that all the header file 244.\" excerpts appear to line up cleanly 245.Bd -literal -offset indent 246UVM_PROT_READ 0x01 read allowed 247UVM_PROT_WRITE 0x02 write allowed 248UVM_PROT_EXEC 0x04 execute allowed 249.Ed 250.Pp 251The 252.Dq obj 253and 254.Dq amap 255fields are pointers to, and offsets into, the underlying uvm_object or 256vm_amap object. 257The value for resident is always unknown because digging such 258information out of the kernel is beyond the scope of this application. 259.Pp 260The two output styles that mirror the contents of the 261.Pa /proc 262file system 263appear as follows: 264.Bd -literal -offset indent 265$ procmap -m 2660x8048000 0x80b1000 r-x rwx COW NC 1 0 0 2670x80b1000 0x80b3000 rw- rwx COW NC 1 0 0 2680x80b3000 0x80ba000 rw- rwx COW NNC 1 0 0 2690x80ba000 0x80be000 rwx rwx COW NNC 1 0 0 270\&... 271 272$ procmap -l 27308048000-080b1000 r-xp 00000000 00:00 70173 /bin/sh 274080b1000-080b3000 rw-p 00068000 00:00 70173 /bin/sh 275080b3000-080ba000 rw-p 00000000 00:00 0 276080ba000-080be000 rwxp 00000000 00:00 0 277\&... 278.Ed 279.Pp 280Here the protection and maximum protection values are indicated with 281.Sq r , 282.Sq w , 283and 284.Sq x 285characters, indicating read permission, write permission, and execute 286permission, respectively. 287The 288.Dq COW , 289.Dq NC , 290and 291.Dq NNC 292values that follow indicate, again, that the map is marked for copy on 293write and either needs or does not need a copy. 294It is also possible 295to see the value 296.Dq NCOW 297here, which indicates that an entry will not be copied. 298The three 299following numbers indicate the inheritance type of the map, the wired 300count of the map, and any advice value assigned via 301.Xr madvise 2 . 302.Pp 303In the second form, the permissions indicated are followed by a 304.Sq p 305or 306.Sq s 307character indicating whether the map entry is private or shared (copy 308on write or not), and the numbers are the offset into the underlying 309object, the device and numbers of the object if it is a file, and the 310path to the file (if available). 311.Pp 312As noted above (see section 313.Sx DESCRIPTION ) , 314the 315.Dq all 316output format is an amalgam of the previous output formats. 317.Bd -literal -offset indent 318$ procmap -a 319Start End Size Offset rwxpc RWX I/W/A ... 32008048000-080b0fff 420k 00000000 r-xp+ (rwx) 1/0/0 ... 321\&... 322.Ed 323.Pp 324In this format, the column labeled 325.Dq rwxpc 326contains the permissions for the mapping along with the shared/private 327flag, and a character indicating whether the mapping needs to be 328copied on write 329.Pq Sq + 330or has already been copied 331.Pq Sq - 332and is followed by a column that indicates the maximum permissions for 333the map entry. 334The column labeled 335.Dq I/W/A 336indicates the inheritance, wired, and advice values for the map entry, 337as previously described. 338.Sh SEE ALSO 339.Xr ls 1 , 340.\" .Xr stat 1 , 341.Xr madvise 2 , 342.Xr mmap 2 , 343.Xr kvm 3 , 344.Xr ddb 4 , 345.Xr mount_procfs 8 , 346.Xr namei 9 , 347.Xr vnode 9 348.Sh HISTORY 349The 350.Nm 351utility first appeared in 352.Ox 3.5 . 353It was derived from the 354.Nx 355utility known as 356.Dq pmap . 357.Sh AUTHORS 358The 359.Nm 360utility and documentation was written by 361.An Andrew Brown Aq Mt atatat@netbsd.org . 362.Sh BUGS 363Very little will work unless 364.Nm 365is reading from the correct kernel in order to retrieve the 366proper symbol information. 367.Pp 368Since processes can change state while 369.Nm 370is running, some of the information printed may be inaccurate. 371This is especially important to consider when examining the kernel's map, 372since merely executing 373.Nm 374will cause some of the information to change. 375.Pp 376The pathnames to files backing certain vnodes (such as the text and 377data sections of programs and shared libraries) are extracted from the 378kernel's namei cache which is considerably volatile. 379If a path is not 380found there in its entirety, as much information as was available 381will be printed. 382In most cases, simply running 383.Xr ls 1 384.\" or 385.\" .Xr stat 1 386with the expected path to the file will cause the information to be 387reentered into the cache. 388.Pp 389The Solaris version 390.Pq Dq pmap 391has some interesting command line flags that would be nice to emulate here. 392In particular, the 393.Fl r 394option that lists a process's reserved addresses, and the 395.Fl x 396option that prints resident/shared/private mapping details for each 397entry. 398.Pp 399Some of the output modes can be or are wider than the standard 80 400columns of a terminal. 401Some sort of formatting might be nice. 402