share/man/man1/madv.so.1.1

   1 '\" te
   2 .\"  Copyright (c) 2002, 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 MADV.SO.1 1 "Feb 15, 2002"
   7 .SH NAME
   8 madv.so.1 \- madv library
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/lib/madv.so.1\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBmadv.so.1\fR shared object provides a means by which the VM advice can
  19 be selectively configured for a launched process (or processes) and its
  20 descendants. To enable \fBmadv.so.1\fR, the following string needs to be
  21 present in the environment (see \fBld.so.1\fR(1)) along with one or more
  22 \fBMADV\fR environment variables:
  23 .sp
  24 .in +2
  25 .nf
  26 \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR
  27 .fi
  28 .in -2
  29 .sp
  30
  31 .SH ENVIRONMENT VARIABLES
  32 .sp
  33 .LP
  34 If the \fBmadv.so.1\fR shared object is specified in the \fBLD_PRELOAD\fR list,
  35 the following environment variables are read by the \fBmadv\fR shared object to
  36 determine to which created process(es) to apply the specified advice.
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fBMADV\fR=\fIadvice\fR \fR
  41 .ad
  42 .RS 27n
  43 \fBMADV\fR specifies the VM advice to use for all heap, shared memory, and mmap
  44 regions in the process address                 space. This advice is applied to
  45 all created processes.
  46 .sp
  47 Values for \fIadvice\fR correspond to values in <sys/mman.h> used in
  48 \fBmadvise\fR(3C) to specify memory access patterns:
  49 .br
  50 .in +2
  51 normal
  52 .in -2
  53 .br
  54 .in +2
  55 random
  56 .in -2
  57 .br
  58 .in +2
  59 sequential
  60 .in -2
  61 .br
  62 .in +2
  63 access_lwp
  64 .in -2
  65 .br
  66 .in +2
  67 access_many
  68 .in -2
  69 .br
  70 .in +2
  71 access_default
  72 .in -2
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBMADVCFGFILE\fR=\fIconfig-file\fR\fR
  79 .ad
  80 .RS 27n
  81 \fIconfig-file\fR is a text file which contains one or more \fBmadv\fR
  82 configuration entries of the form:
  83 .sp
  84 .in +2
  85 .nf
  86 \fIexec-name\fR \fIexec-args\fR:\fIadvice-opts\fR
  87 .fi
  88 .in -2
  89 .sp
  90
  91 Advice specified in \fIconfig-file\fR takes precedence over that specified by
  92 the \fBMADV\fR environment variable. When \fBMADVCFGFILE\fR is not set, advice
  93 is taken from file \fB/etc/madv.conf\fR if it exists.
  94 .sp
  95 \fIexec-name\fR specifies the name of an application or executable. The
  96 corresponding advice is set for newly created processes (see
  97 \fBgetexecname\fR(3C)) that match the first \fIexec-name\fR found in the file.
  98 .sp
  99 \fIexec-name\fR can be a full pathname, a base name, or a pattern string. See
 100 \fBFile Name Generation\fR in \fBsh\fR(1) for a discussion of pattern matching.
 101 .sp
 102 \fIexec-args\fR is an optionally specified pattern string to match against
 103 arguments. Advice is set only if \fIexec-args\fR is not specified or occurs
 104 within the arguments to \fIexec-name\fR.
 105 .sp
 106 \fIadvice-opts\fR is a comma-separated list specifying the advice for various
 107 memory region(s):
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBmadv\fR=\fIadvice\fR\fR
 112 .ad
 113 .RS 21n
 114 Applies to all heap, shared memory, and mmap regions in the process address
 115 space.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBheap\fR=\fIadvice\fR\fR
 122 .ad
 123 .RS 21n
 124 The heap is defined to be the brk area (see \fBbrk\fR(2)). Applies to the
 125 existing heap and for any additional heap memory allocated in the future.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBshm\fR=\fIadvice\fR\fR
 132 .ad
 133 .br
 134 .na
 135 \fB\fBism\fR=\fIadvice\fR\fR
 136 .ad
 137 .br
 138 .na
 139 \fB\fBdism\fR=\fIadvice\fR\fR
 140 .ad
 141 .RS 21n
 142 Shared memory segments (see \fBshmat\fR(2)) attached using any flags, flag
 143 \fBSHM_SHARE_MMU\fR, or flag \fBSHM_PAGEABLE\fR  respectively. Options
 144 \fBism\fR and \fBdism\fR take precedence over option \fBshm\fR.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBmap\fR=\fIadvice\fR\fR
 151 .ad
 152 .br
 153 .na
 154 \fB\fBmapshared\fR=\fIadvice\fR\fR
 155 .ad
 156 .br
 157 .na
 158 \fB\fBmapprivate\fR=\fIadvice\fR\fR
 159 .ad
 160 .br
 161 .na
 162 \fB\fBmapanon\fR=\fIadvice\fR\fR
 163 .ad
 164 .RS 21n
 165 Mappings established through \fBmmap\fR(2) using any flags, flag
 166 \fBMAP_SHARED\fR, flag \fBMAP_PRIVATE\fR, or flag \fBMAP_ANON\fR, respectively.
 167 Options \fBmapshared\fR, \fBmapprivate\fR, and \fBmapanon\fR take precedence
 168 over option \fBmap\fR. Option \fBmapanon\fR takes precedence over
 169 \fBmapshared\fR and \fBmapprivate\fR.
 170 .RE
 171
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBMADVERRFILE\fR=\fIpathname\fR\fR
 178 .ad
 179 .RS 27n
 180 By default, error messages are logged via \fBsyslog\fR(3C) using level
 181 \fBLOG_ERR\fR and facility \fBLOG_USER\fR. If \fBMADVERRFILE\fR contains a
 182 valid \fIpathname\fR (such as \fB/dev/stderr\fR), error messages will be logged
 183 there instead.
 184 .RE
 185
 186 .SH EXAMPLES
 187 .LP
 188 \fBExample 1 \fRApplying advice to all ISM segments
 189 .sp
 190 .LP
 191 The following configuration applies advice to all ISM segments for application
 192 \fB/usr/bin/foo\fR:
 193
 194 .sp
 195 .in +2
 196 .nf
 197 example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR
 198 example$ \fBMADVCFGFILE=madvcfg\fR
 199 example$ \fBexport LD_PRELOAD MADVCFGFILE\fR
 200 example$ \fBcat $MADVCFGFILE\fR
 201     /usr/bin/foo:ism=access_lwp
 202 .fi
 203 .in -2
 204 .sp
 205
 206 .LP
 207 \fBExample 2 \fRSetting advice for all applications with exception
 208 .sp
 209 .LP
 210 The following configuration sets advice for all applications with the exception
 211 of \fBls\fR.
 212
 213 .sp
 214 .in +2
 215 .nf
 216 example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR
 217 example$ \fBMADV=access_many\fR
 218 example$ \fBMADVCFGFILE=madvcfg\fR
 219 example$ \fBexport LD_PRELOAD MADV MADVCFGFILE\fR
 220 example$ \fBcat $MADVCFGFILE\fR
 221     ls:
 222 .fi
 223 .in -2
 224 .sp
 225
 226 .LP
 227 \fBExample 3 \fRPrecedence rules (continuation from Example 2)
 228 .sp
 229 .LP
 230 Because \fBMADVCFGFILE\fR takes precedence over \fBMADV\fR,
 231 specifying '\fB*\fR' (pattern match all) for the \fIexec-name\fR of the last \fBmadv\fR
 232 configuration entry would be equivalent to setting \fBMADV\fR. The following is
 233 equivalent to example 2:
 234
 235 .sp
 236 .in +2
 237 .nf
 238 example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR
 239 example$ \fBMADVCFGFILE=madvcfg\fR
 240 example$ \fBexport LD_PRELOAD MADVCFGFILE\fR
 241 example$ \fBcat $MADVCFGFILE\fR
 242     ls:
 243     *:madv=access_many
 244 .fi
 245 .in -2
 246 .sp
 247
 248 .LP
 249 \fBExample 4 \fRApplying advice for different regions
 250 .sp
 251 .LP
 252 The following configuration applies one type of advice for mmap regions and
 253 different advice for heap and shared memory regions for a select set of
 254 applications with exec names that begin with \fBfoo\fR:
 255
 256 .sp
 257 .in +2
 258 .nf
 259 example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR
 260 example$ \fBMADVCFGFILE=madvcfg\fR
 261 example$ \fBexport LD_PRELOAD MADVCFGFILE\fR
 262 example$ \fBcat $MADVCFGFILE\fR
 263     foo*:madv=access_many,heap=sequential,shm=access_lwp
 264 .fi
 265 .in -2
 266 .sp
 267
 268 .LP
 269 \fBExample 5 \fRApplying advice selectively
 270 .sp
 271 .LP
 272 The following configuration applies advice for the heap of applications
 273 beginning with \fBora\fR that have \fBora1\fR as an argument:
 274
 275 .sp
 276 .in +2
 277 .nf
 278 example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR
 279 example$ \fBMADVCFGFILE=madvcfg\fR
 280 example$ \fBexport LD_PRELOAD MADVCFGFILE\fR
 281 example$ \fBcat $MADVCFGFILE\fR
 282     ora* ora1:heap=access_many
 283 .fi
 284 .in -2
 285 .sp
 286
 287 .SH FILES
 288 .sp
 289 .ne 2
 290 .na
 291 \fB\fB/etc/madv.conf\fR \fR
 292 .ad
 293 .RS 19n
 294 Configuration file
 295 .RE
 296
 297 .SH SEE ALSO
 298 .sp
 299 .LP
 300 \fBcat\fR(1), \fBld.so.1\fR(1), \fBproc\fR(1), \fBsh\fR(1), \fBbrk\fR(2),
 301 \fBexec\fR(2), \fBfork\fR(2), \fBmmap\fR(2), \fBmemcntl\fR(2), \fBshmat\fR(2),
 302 \fBgetexecname\fR(3C), \fBmadvise\fR(3C), \fBsyslog\fR(3C), \fBproc\fR(4),
 303 \fBattributes\fR(5)
 304 .SH NOTES
 305 .sp
 306 .LP
 307 The advice is inherited. A child process has the same advice         as its
 308 parent. On \fBexec()\fR (see \fBexec\fR(2)), the advice is set back to the
 309 default system advice unless different advice has been configured via the
 310 \fBmadv\fR shared object.
 311 .sp
 312 .LP
 313 Advice is only applied to \fBmmap\fR regions explicitly created by the user
 314 program. Those regions established by the run-time linker or by system
 315 libraries making direct system calls (for example, libthread allocations for
 316 thread stacks) are not affected.