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