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