usr/src/man/man1/mpss.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 MPSS.SO.1 1 "Feb 20, 2002"
   7 .SH NAME
   8 mpss.so.1 \- shared object for setting preferred page size
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBmpss.so.1\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBmpss.so.1\fR shared object provides a means by which the preferred stack
  19 and/or heap page size can be selectively configured for launched processes and
  20 their descendants. To enable \fBmpss.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 \fBMPSS\fR (Multiple Page Size Support) environment variables:
  23 .sp
  24 .in +2
  25 .nf
  26 \fBLD_PRELOAD=$LD_PRELOAD:mpss.so.1\fR
  27 .fi
  28 .in -2
  29 .sp
  30
  31 .SH ENVIRONMENT VARIABLES
  32 .sp
  33 .LP
  34 Once preloaded, the \fBmpss.so.1\fR shared object reads the following
  35 environment variables to determine any preferred page size requirements and any
  36 processes these may be specific to.
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fBMPSSHEAP\fR=\fIsize\fR \fR
  41 .ad
  42 .br
  43 .na
  44 \fB\fBMPSSSTACK\fR=\fIsize\fR\fR
  45 .ad
  46 .RS 27n
  47 \fBMPSSHEAP\fR and \fBMPSSSTACK\fR specify the preferred page sizes for the
  48 heap and stack, respectively. The specified page size(s) are applied to all
  49 created processes.
  50 .sp
  51 \fIsize\fR must be a supported page size (see \fBpagesize\fR(1)) or \fB0\fR, in
  52 which case the system will select an appropriate page size (see
  53 \fBmemcntl\fR(2)).
  54 .sp
  55 \fIsize\fR can be qualified with \fBK\fR, \fBM\fR, \fBG\fR, or \fBT\fR to
  56 specify Kilobytes, Megabytes, Gigabytes, or Terabytes respectively.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBMPSSCFGFILE\fR=\fIconfig-file\fR\fR
  63 .ad
  64 .RS 27n
  65 \fIconfig-file\fR is a text file which contains one or more \fBmpss\fR
  66 configuration entries of the form:
  67 .sp
  68 .in +2
  69 .nf
  70 \fIexec-name\fR \fIexec-args\fR:\fIheap-size\fR:\fIstack-size\fR
  71 .fi
  72 .in -2
  73 .sp
  74
  75 \fIexec-name\fR specifies the name of an application or executable. The
  76 corresponding preferred page size(s) are set for newly created processes (see
  77 \fBgetexecname\fR(3C)) that match the first \fIexec-name\fR found in the file.
  78 .sp
  79 \fIexec-name\fR can be a full pathname, a base name or a pattern string. See
  80 \fBFile Name Generation\fR in \fBsh\fR(1) for a discussion of pattern matching.
  81 .sp
  82 \fIexec-args\fR is an optionally specified pattern string to match against
  83 arguments. Preferred page size(s) are set only if \fIexec-args\fR is not
  84 specified or occurs within the arguments to \fIexec-name\fR.
  85 .sp
  86 If \fIheap-size\fR and/or \fIstack-size\fR are not specified, the corresponding
  87 preferred page size(s) will not be set.
  88 .sp
  89 \fBMPSSCFGFILE\fR takes precedence over \fBMPSSHEAP\fR and \fBMPSSSTACK\fR.
  90 When \fBMPSSCFGFILE\fR is not set, preferred page size settings are taken from
  91 file \fB/etc/mpss.conf\fR if it exists.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBMPSSERRFILE\fR=\fIpathname\fR\fR
  98 .ad
  99 .RS 27n
 100 By default, error messages are logged via \fBsyslog\fR(3C) using level
 101 \fBLOG_ERR\fR and facility \fBLOG_USER\fR. If \fBMPSSERRFILE\fR contains a
 102 valid \fIpathname\fR (such as \fB/dev/stderr\fR), error messages will be logged
 103 there instead.
 104 .RE
 105
 106 .SH EXAMPLES
 107 .LP
 108 \fBExample 1 \fRConfiguring preferred page sizes using MPSSCFGFILE
 109 .sp
 110 .LP
 111 The following Bourne shell commands (see \fBsh\fR(1)) configure the preferred
 112 page sizes to a select set of applications with exec names that begin with
 113 \fBfoo\fR, using the \fBMPSSCFGFILE\fR environment variable. The \fBMPSS\fR
 114 configuration file, \fBmpsscfg\fR, is assumed to have been previously created
 115 via a text editor like \fBvi\fR(1). The \fBcat\fR(1) command is only dumping
 116 out the contents.
 117
 118 .sp
 119 .in +2
 120 .nf
 121 example$ \fBLD_PRELOAD=$LD_PRELOAD:mpss.so.1\fR
 122 example$ \fBMPSSCFGFILE=mpsscfg\fR
 123 example$ \fBexport LD_PRELOAD MPSSCFGFILE\fR
 124 example$ \fBcat $MPSSCFGFILE\fR
 125 foo*:512K:64K
 126 .fi
 127 .in -2
 128 .sp
 129
 130 .sp
 131 .LP
 132 Once the application has been started, \fBpmap\fR (see \fBproc\fR(1)) can be
 133 used to view the actual page sizes configured:
 134
 135 .sp
 136 .in +2
 137 .nf
 138 example$ \fBfoobar &\fR
 139 example$ \fBpmap -s `pgrep foobar`\fR
 140 .fi
 141 .in -2
 142 .sp
 143
 144 .sp
 145 .LP
 146 If the desired page size is not configured (shown in the \fBpmap\fR output), it
 147 may be due to errors in the \fBMPSS\fR configuration file or environment
 148 variables. Check the error log (by default: \fB/var/adm/messages\fR) for
 149 errors.
 150
 151 .sp
 152 .LP
 153 If no errors can be found, resource or alignment constraints may be
 154 responsible. See the NOTES section.
 155
 156 .LP
 157 \fBExample 2 \fRConfiguring preferred page sizes using MPSSHEAP and MPSSSTACK
 158 .sp
 159 .LP
 160 The following Bourne shell commands configure \fB512K\fR heap and \fB64K\fR
 161 stack preferred page sizes for all applications using the \fBMPSSHEAP\fR and
 162 \fBMPSSSTACK\fR environment variables.
 163
 164 .sp
 165 .in +2
 166 .nf
 167 example$ \fBLD_PRELOAD=$LD_PRELOAD:mpss.so.1\fR
 168 example$ \fBMPSSHEAP=512K\fR
 169 example$ \fBMPSSSTACK=64K\fR
 170 example$ \fBexport LD_PRELOAD MPSSHEAP MPSSSTACK\fR
 171 .fi
 172 .in -2
 173 .sp
 174
 175 .LP
 176 \fBExample 3 \fRPrecedence rules (continuation from Example 2)
 177 .sp
 178 .LP
 179 The preferred page size configuration in \fBMPSSCFGFILE\fR overrides
 180 \fBMPSSHEAP\fR and \fBMPSSTACK\fR. Appending the following commands to those in
 181 \fBExample 2\fR would mean that all applications will be configured with
 182 \fB512K\fR heap and \fB64K\fR stack preferred page sizes with the exception of
 183 those applications, the \fBls\fR command, and all applications beginning with
 184 \fBora\fR that have \fBora1\fR as an argument, in the configuration file.
 185
 186 .sp
 187 .in +2
 188 .nf
 189 example$ \fBMPSSCFGFILE=mpsscfg2\fR
 190 example$ \fBexport MPSSCFGFILE\fR
 191 example$ \fBcat $MPSSCFGFILE\fR
 192 ls::
 193 ora* ora1:4m:4m
 194 .fi
 195 .in -2
 196 .sp
 197
 198 .SH FILES
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fB/usr/lib/ld/map.bssalign\fR \fR
 203 .ad
 204 .RS 29n
 205 A template link-editor \fBmapfile\fR for aligning bss (see NOTES).
 206 .RE
 207
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fB/etc/mpss.conf\fR\fR
 212 .ad
 213 .RS 29n
 214 Configuration file
 215 .RE
 216
 217 .SH ATTRIBUTES
 218 .sp
 219 .LP
 220 See \fBattributes\fR(5) for descriptions of the following attributes:
 221 .sp
 222
 223 .sp
 224 .TS
 225 box;
 226 c | c
 227 l | l .
 228 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 229 _
 230 Interface Stability     Evolving
 231 .TE
 232
 233 .SH SEE ALSO
 234 .sp
 235 .LP
 236 \fBcat\fR(1), \fBld\fR(1), \fBld.so.1\fR(1), \fBpagesize\fR(1), \fBppgsz\fR(1),
 237 \fBproc\fR(1), \fBsh\fR(1), \fBvi\fR(1), \fBexec\fR(2), \fBfork\fR(2),
 238 \fBmemcntl\fR(2), \fBgetexecname\fR(3C), \fBgetpagesize\fR(3C),
 239 \fBsyslog\fR(3C), \fBproc\fR(4), \fBattributes\fR(5)
 240 .SH NOTES
 241 .sp
 242 .LP
 243 The heap and stack preferred page sizes are inherited. A child process has the
 244 same preferred page sizes as its parent. On \fBexec\fR(2), the preferred page
 245 sizes are set back to the default system page size unless a preferred page size
 246 has been configured via the \fBmpss\fR shared object.
 247 .sp
 248 .LP
 249 \fBppgsz\fR(1), a proc tool, can also be used to set the preferred stack and/or
 250 heap page sizes. It cannot selectively configure the page size for descendents
 251 based on name matches.
 252 .sp
 253 .LP
 254 See also NOTES under \fBppgsz\fR(1).