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