1 '\" te 2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .TH PMADVISE 1 "Sep 25, 2008" 7 .SH NAME 8 pmadvise \- applies advice about memory to a process 9 .SH SYNOPSIS 10 .LP 11 .nf 12 \fBpmadvise\fR \fB-o\fR \fIoption\fR[,\fIoption\fR] [\fB-F\fR] [\fB-l\fR] [\fB-v\fR] \fIpid\fR... 13 .fi 14 15 .SH DESCRIPTION 16 .LP 17 \fBpmadvise\fR applies advice about how memory is used in the specified process 18 using \fBmadvise\fR(3C). 19 .sp 20 .LP 21 \fBpmadvise\fR allows users to apply advice to a specific sub-range at a 22 specific instant in time. \fBpmadvise\fR differs from \fBmadv.so.1\fR(1) in 23 that \fBmadv.so.1\fR(1) applies the advice throughout execution of the target 24 program to all segments of a specified type. 25 .SH OPTIONS 26 .LP 27 The following options are supported: 28 .sp 29 .ne 2 30 .na 31 \fB\fB-F\fR\fR 32 .ad 33 .RS 6n 34 Force by grabbing the target process even if another process has control. 35 .sp 36 You should exercise caution when using the \fB-F\fR option. See \fBproc\fR(1). 37 .RE 38 39 .sp 40 .ne 2 41 .na 42 \fB\fB-l\fR\fR 43 .ad 44 .RS 6n 45 Show unresolved dynamic linker map names. 46 .RE 47 48 .sp 49 .ne 2 50 .na 51 \fB\fB-o\fR\fR 52 .ad 53 .RS 6n 54 Specify advice to apply in the following form: 55 .sp 56 .in +2 57 .nf 58 private=\fBadvice\fR 59 shared=\fBadvice\fR 60 heap=\fBadvice\fR 61 stack=\fBadvice\fR 62 \fBaddress\fR[:\fBlength\fR]=\fBadvice\fR 63 .fi 64 .in -2 65 .sp 66 67 where the \fBadvice\fR can be one of the following: 68 .sp 69 .in +2 70 .nf 71 normal 72 random 73 sequential 74 willneed 75 dontneed 76 free 77 access_lwp 78 access_many 79 access_default 80 purge 81 .fi 82 .in -2 83 .sp 84 85 An \fBaddress\fR and \fBlength\fR can be given to specify a subrange to apply 86 the advice.The \fBaddress\fR should be hexadecimal and the \fBlength\fR should 87 be in bytes by default. 88 .sp 89 If \fBlength\fR is not specified and the starting address refers to the start 90 of a segment, the advice is applied to that segment. \fBlength\fR can be 91 qualified by \fBK\fR, \fBM\fR, \fBG\fR, \fBT\fR, \fBP\fR, or \fBE\fR to specify 92 kilobytes, megabytes, gigabytes, terabytes, or exabytes respectively as the 93 unit of measure. 94 .RE 95 96 .sp 97 .ne 2 98 .na 99 \fB\fB-v\fR\fR 100 .ad 101 .RS 6n 102 Print verbose output. Display output as \fBpmap\fR(1) does, showing what advice 103 is being applied where. This can be useful when the advice is being applied to 104 a named region (for example, private, shared, and so forth) to get feedback on 105 exactly where the advice is being applied. 106 .RE 107 108 .sp 109 .LP 110 \fBpmadvise\fR tries to process all legal options. If an illegal address range 111 is specified, an error message is printed and the offending option is skipped. 112 \fBpmadvise\fR quits without processing any options and prints a usage message 113 when there is a syntax error. 114 .sp 115 .LP 116 If conflicting advice is given on a region, the order of precedence is from 117 most specific advice to least, that is, most general. In other words, advice 118 specified for a particuliar address range takes precedence over advice for heap 119 and stack which in turn takes precedence over advice for private and shared 120 memory. 121 .sp 122 .LP 123 Moreover, the advice in each of the following groups are mutually exclusive 124 from the other advice within the same group: 125 .sp 126 .in +2 127 .nf 128 MADV_NORMAL, MADV_RANDOM, MADV_SEQUENTIAL 129 MADV_WILLNEED, MADV_DONTNEED, MADV_FREE, MADV_PURGE 130 MADV_ACCESS_DEFAULT, MADV_ACCESS_LWP, MADV_ACCESS_MANY 131 .fi 132 .in -2 133 .sp 134 135 .SH OPERANDS 136 .LP 137 The following operands are supported: 138 .sp 139 .ne 2 140 .na 141 \fB\fIpid\fR\fR 142 .ad 143 .RS 7n 144 Process ID. 145 .RE 146 147 .SH EXAMPLES 148 \fBExample 1 \fRApplying Advice to a Segment at Specified Address 149 .sp 150 .LP 151 The following example applies advice to a segment at a specified address: 152 153 .sp 154 .in +2 155 .nf 156 % pmap $$ 157 100666: tcsh 158 00010000 312K r-x-- /usr/bin/tcsh 159 0006C000 48K rwx-- /usr/bin/tcsh 160 00078000 536K rwx-- [ heap ] 161 FF100000 856K r-x-- /lib/libc.so.1 162 FF1E6000 32K rwx-- /lib/libc.so.1 163 FF1EE000 8K rwx-- /lib/libc.so.1 164 FF230000 168K r-x-- /lib/libcurses.so.1 165 FF26A000 32K rwx-- /lib/libcurses.so.1 166 FF272000 8K rwx-- /lib/libcurses.so.1 167 FF280000 576K r-x-- /lib/libnsl.so.1 168 FF310000 40K rwx-- /lib/libnsl.so.1 169 FF31A000 24K rwx-- /lib/libnsl.so.1 170 FF364000 8K rwxs- [ anon ] 171 FF370000 48K r-x-- /lib/libsocket.so.1 172 FF38C000 8K rwx-- /lib/libsocket.so.1 173 FF3A0000 8K r-x-- /platform/sun4u-us3/lib/libc_psr.so.1 174 FF3B0000 176K r-x-- /lib/ld.so.1 175 FF3EC000 8K rwx-- /lib/ld.so.1 176 FF3EE000 8K rwx-- /lib/ld.so.1 177 FFBE6000 104K rw--- [ stack ] 178 % 179 % pmadvise -o 78000=access_lwp $$ 180 181 % 182 .fi 183 .in -2 184 .sp 185 186 .LP 187 \fBExample 2 \fRUsing the \fB-v\fR Option 188 .sp 189 .LP 190 The following example displays verbose output from \fBpmadvise\fR: 191 192 .sp 193 .in +2 194 .nf 195 196 % pmadvise -o heap=access_lwp,stack=access_default -v $$ 197 1720: -sh 198 00010000 88K r-x-- /sbin/sh 199 00036000 8K rwx-- /sbin/sh 200 00038000 16K rwx-- [ heap ] <= access_lwp 201 FF250000 24K r-x-- /lib/libgen.so.1 202 FF266000 8K rwx-- /lib/libgen.so.1 203 FF272000 8K rwxs- [ anon ] 204 FF280000 840K r-x-- /lib/libc.so.1 205 FF362000 32K rwx-- /lib/libc.so.1 206 FF36A000 16K rwx-- /lib/libc.so.1 207 FF380000 8K r-x-- /platform/sun4u-us3/lib/libc_psr.so.1 208 FF390000 64K rwx-- [ anon ] 209 FF3B0000 168K r-x-- /lib/ld.so.1 210 FF3EA000 8K rwx-- /lib/ld.so.1 211 FF3EC000 8K rwx-- /lib/ld.so.1 212 FFBFE000 8K rw--- [ stack ] <= access_default 213 .fi 214 .in -2 215 .sp 216 217 .SH EXIT STATUS 218 .LP 219 The following exit values are returned: 220 .sp 221 .ne 2 222 .na 223 \fB\fB0\fR\fR 224 .ad 225 .RS 12n 226 Successful completion. 227 .RE 228 229 .sp 230 .ne 2 231 .na 232 \fB\fBnon-zero\fR\fR 233 .ad 234 .RS 12n 235 An error occurred. 236 .RE 237 238 .SH FILES 239 .ne 2 240 .na 241 \fB\fB/proc/*\fR\fR 242 .ad 243 .RS 19n 244 Process files 245 .RE 246 247 .sp 248 .ne 2 249 .na 250 \fB\fB/usr/prob/lib/*\fR\fR 251 .ad 252 .RS 19n 253 \fBproc\fR tools support files 254 .RE 255 256 .SH ATTRIBUTES 257 .LP 258 See \fBattributes\fR(5) for descriptions of the following attributes: 259 .sp 260 261 .sp 262 .TS 263 box; 264 c | c 265 l | l . 266 ATTRIBUTE TYPE ATTRIBUTE VALUE 267 _ 268 Interface Stability See below. 269 .TE 270 271 .sp 272 .LP 273 The command syntax is Evolving. The output formats are Unstable. 274 .SH SEE ALSO 275 .LP 276 \fBmadv.so.1\fR(1), \fBpmap\fR(1), \fBproc\fR(1), \fBmadvise\fR(3C), 277 \fBattributes\fR(5)