share/man/man1/pmadvise.1

   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 FF3A0000       8K r-x--  /platform/sun4u-us3/lib/libc_psr.so.1
 172 FF3B0000     176K r-x--  /lib/ld.so.1
 173 FF3EC000       8K rwx--  /lib/ld.so.1
 174 FF3EE000       8K rwx--  /lib/ld.so.1
 175 FFBE6000     104K rw---    [ stack ]
 176 %
 177 % pmadvise -o 78000=access_lwp $$
 178
 179 %
 180 .fi
 181 .in -2
 182 .sp
 183
 184 .LP
 185 \fBExample 2 \fRUsing the \fB-v\fR Option
 186 .sp
 187 .LP
 188 The following example displays verbose output from \fBpmadvise\fR:
 189
 190 .sp
 191 .in +2
 192 .nf
 193
 194 % pmadvise -o heap=access_lwp,stack=access_default -v $$
 195 1720:   -sh
 196 00010000      88K r-x--  /bin/sh
 197 00036000       8K rwx--  /bin/sh
 198 00038000      16K rwx--    [ heap ]           <= access_lwp
 199 FF250000      24K r-x--  /lib/libgen.so.1
 200 FF266000       8K rwx--  /lib/libgen.so.1
 201 FF272000       8K rwxs-    [ anon ]
 202 FF280000     840K r-x--  /lib/libc.so.1
 203 FF362000      32K rwx--  /lib/libc.so.1
 204 FF36A000      16K rwx--  /lib/libc.so.1
 205 FF380000       8K r-x--  /platform/sun4u-us3/lib/libc_psr.so.1
 206 FF390000      64K rwx--    [ anon ]
 207 FF3B0000     168K r-x--  /lib/ld.so.1
 208 FF3EA000       8K rwx--  /lib/ld.so.1
 209 FF3EC000       8K rwx--  /lib/ld.so.1
 210 FFBFE000       8K rw---    [ stack ]          <= access_default
 211 .fi
 212 .in -2
 213 .sp
 214
 215 .SH EXIT STATUS
 216 .LP
 217 The following exit values are returned:
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fB0\fR\fR
 222 .ad
 223 .RS 12n
 224 Successful completion.
 225 .RE
 226
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fBnon-zero\fR\fR
 231 .ad
 232 .RS 12n
 233 An error occurred.
 234 .RE
 235
 236 .SH FILES
 237 .ne 2
 238 .na
 239 \fB\fB/proc/*\fR\fR
 240 .ad
 241 .RS 19n
 242 Process files
 243 .RE
 244
 245 .sp
 246 .ne 2
 247 .na
 248 \fB\fB/usr/prob/lib/*\fR\fR
 249 .ad
 250 .RS 19n
 251 \fBproc\fR tools support files
 252 .RE
 253
 254 .SH ATTRIBUTES
 255 .LP
 256 See \fBattributes\fR(5) for descriptions of the following attributes:
 257 .sp
 258
 259 .sp
 260 .TS
 261 box;
 262 c | c
 263 l | l .
 264 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 265 _
 266 Interface Stability     See below.
 267 .TE
 268
 269 .sp
 270 .LP
 271 The command syntax is Evolving. The output formats are Unstable.
 272 .SH SEE ALSO
 273 .LP
 274 \fBmadv.so.1\fR(1), \fBpmap\fR(1), \fBproc\fR(1), \fBmadvise\fR(3C),
 275 \fBattributes\fR(5)