usr/src/man/man1/ppgsz.1

   1 '\" te
   2 .\" Copyright (c) 2003, 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 PPGSZ 1 "Jan 23, 2003"
   7 .SH NAME
   8 ppgsz \- set preferred page size for stack, heap, and/or other anonymous
   9 segments
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/usr/bin/ppgsz\fR [\fB-F\fR] \fB-o\fR \fIoption\fR[,\fIoption\fR] \fIcmd\fR | \fB-p\fR \fIpid\fR...
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The \fBppgsz\fR utility sets the preferred page size for stack, heap, and/or
  20 other anonymous segments for the target process(es), that is, the launched
  21 \fIcmd\fR or the process(es) in the pid list. \fBppgsz\fR stops the target
  22 process(es) while changing the page size. See \fBmemcntl\fR(2).
  23 .SH OPTIONS
  24 .sp
  25 .LP
  26 The following options are supported:
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fB-F\fR\fR
  31 .ad
  32 .RS 22n
  33 Force. Sets the preferred page size options(s) for target process(es) even if
  34 controlled by other process(es). Caution should be exercised when using the
  35 \fB-F\fR flag. See \fBproc\fR(1).
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fB-o\fR \fIoption\fR[,\fIoption\fR]\fR
  42 .ad
  43 .RS 22n
  44 The \fIoption\fRs are:
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBheap\fR=\fIsize\fR\fR
  49 .ad
  50 .RS 14n
  51 This option specifies the preferred page size for the heap of the target
  52 process(es). \fBheap\fR is defined to be the bss (uninitialized data) and the
  53 brk area that immediately follows the bss (see \fBbrk\fR(2)). The preferred
  54 heap page size is set for the existing heap and for any additional heap memory
  55 allocated in the future. See NOTES.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBstack\fR=\fIsize\fR\fR
  62 .ad
  63 .RS 14n
  64 This option specifies the preferred page size for the stack of the target
  65 process(es). The preferred stack page size is set for the existing stack and
  66 newly allocated parts of the stack as it expands.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBanon\fR=\fIsize\fR\fR
  73 .ad
  74 .RS 14n
  75 This option specifies the preferred page size for all existing
  76 \fBMAP_PRIVATE\fR anonymous segments of the target process(es),  other than
  77 \fBheap\fR and \fBstack\fR, which are large enough to fit at least one aligned
  78 page of the specified size. For the segments that are large enough, the
  79 preferred page size is set starting at the first size-aligned address in the
  80 segment. The \fBanon\fR preferred pagesize is not applied to \fBMAP_PRIVATE\fR
  81 anonymous segments created in the future. See \fBMAP_ANON\fR in \fBmmap\fR(2).
  82 .sp
  83 Anonymous memory refers to \fBMAP_PRIVATE\fR pages that are not directly
  84 associated with a file in some filesystem. The \fBppgsz\fR command uses
  85 \fBmemcntl\fR(2) to set the preferred page size for anonymous segments. See
  86 \fBMC_HAT_ADVISE\fR in \fBmemcntl\fR(2).
  87 .RE
  88
  89 At least one of the above options must be specified.
  90 .sp
  91 \fIsize\fR must be a supported page size (see \fBpagesize\fR(1)) or \fB0\fR, in
  92 which case the system will select an appropriate page size. See
  93 \fBmemcntl\fR(2).
  94 .sp
  95 \fIsize\fR defaults to bytes and can be specified in octal (\fB0\fR), decimal,
  96 or hexadecimal (\fB0x\fR). The numeric value can be qualified with \fBK\fR,
  97 \fBM\fR, \fBG\fR, or \fBT\fR to specify Kilobytes, Megabytes, Gigabytes, or
  98 Terabytes, respectively. \fB4194304\fR, \fB0x400000\fR, \fB4096K\fR,
  99 \fB0x1000K\fR, and \fB4M\fR are different ways to specify 4 Megabytes.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fB-p\fR \fIpid\fR\fR
 106 .ad
 107 .RS 22n
 108 Sets the preferred page size option(s) for the target process(es) in the
 109 process-id (\fIpid\fR) list following the \fB-p\fR option. The pid list can
 110 also consist of names in the \fB/proc\fR directory. Only the process owner or
 111 the super-user is permitted to set page size.
 112 .sp
 113 \fIcmd\fR is interpreted if \fB-p\fR is not specified. \fBppgsz\fR launches
 114 \fIcmd\fR and applies page size option(s) to the new process.
 115 .sp
 116 The heap and stack preferred page sizes are inherited. Child process(es)
 117 created (see \fBfork\fR(2)) from the launched process or the target process(es)
 118 in the pid list after \fBppgsz\fR completes will inherit the preferred heap and
 119 stack page sizes. The preferred page sizes of all segments are set back to the
 120 default system page size on \fBexec\fR(2) (see \fBgetpagesize\fR(3C)). The
 121 preferred page size for all other anonymous segments is not inherited by
 122 children of the launched or target process(es).
 123 .RE
 124
 125 .SH EXAMPLES
 126 .LP
 127 \fBExample 1 \fRSetting the preferred heap and stack page size
 128 .sp
 129 .LP
 130 The following example sets the preferred heap page size to \fB4M\fR and the
 131 preferred stack page size to \fB512K\fR for all \fBora\fR\(emowned processes
 132 running commands that begin with \fBora\fR:
 133
 134 .sp
 135 .in +2
 136 .nf
 137 example% \fBppgsz -o heap=4M,stack=512K -p `pgrep -u ora '^ora'`\fR
 138 .fi
 139 .in -2
 140 .sp
 141
 142 .LP
 143 \fBExample 2 \fRSetting the preferred anonymous page size
 144 .sp
 145 .LP
 146 The following example sets the preferred page size of existing qualifying
 147 anonymous segments to \fB512k\fR for process ID \fB953\fR:
 148
 149 .sp
 150 .in +2
 151 .nf
 152 example% \fBppgsz -o anon=512k -p 953\fR
 153 .fi
 154 .in -2
 155 .sp
 156
 157 .SH EXIT STATUS
 158 .sp
 159 .LP
 160 If \fIcmd\fR is specified and successfully invoked (see \fBexec\fR(2)), the
 161 exit status of \fBppgsz\fR will be the exit status of \fIcmd\fR. Otherwise,
 162 \fBppgsz\fR will exit with one of the following values:
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fB0\fR \fR
 167 .ad
 168 .RS 7n
 169 Successfully set preferred page size(s) for processes in the pid list.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB125\fR\fR
 176 .ad
 177 .RS 7n
 178 An error occurred in \fBppgsz\fR. Errors include: invalid argument, invalid
 179 page size(s) specified, and failure to set preferred page size(s) for one or
 180 more processes in the pid list or \fIcmd\fR.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fB126\fR\fR
 187 .ad
 188 .RS 7n
 189 \fIcmd\fR was found but could not be invoked.
 190 .RE
 191
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fB127\fR\fR
 196 .ad
 197 .RS 7n
 198 \fIcmd\fR could not be found.
 199 .RE
 200
 201 .SH FILES
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fB/proc/*\fR \fR
 206 .ad
 207 .RS 29n
 208 Process files.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fB/usr/lib/ld/map.bssalign\fR \fR
 215 .ad
 216 .RS 29n
 217 A template link-editor \fBmapfile\fR for aligning bss (see NOTES).
 218 .RE
 219
 220 .SH ATTRIBUTES
 221 .sp
 222 .LP
 223 See \fBattributes\fR(5) for descriptions of the following attributes:
 224 .sp
 225
 226 .sp
 227 .TS
 228 box;
 229 c | c
 230 l | l .
 231 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 232 _
 233 Interface Stability     Evolving
 234 .TE
 235
 236 .SH SEE ALSO
 237 .sp
 238 .LP
 239 \fBld\fR(1), \fBmpss.so.1\fR(1), \fBpagesize\fR(1), \fBpgrep\fR(1),
 240 \fBpmap\fR(1), \fBproc\fR(1), \fBbrk\fR(2), \fBexec\fR(2), \fBfork\fR(2),
 241 \fBmemcntl\fR(2), \fBmmap\fR(2), \fBsbrk\fR(2), \fBgetpagesize\fR(3C),
 242 \fBproc\fR(4), \fBattributes\fR(5)
 243 .sp
 244 .LP
 245 \fILinker and Libraries Guide\fR
 246 .SH NOTES
 247 .sp
 248 .LP
 249 Due to resource constraints, the setting of the preferred page size does not
 250 necessarily guarantee that the target process(es) will get the preferred page
 251 size. Use \fBpmap\fR(1) to view the \fBactual\fR heap and stack page sizes of
 252 the target process(es) (see \fBpmap\fR \fB-s\fR option).
 253 .sp
 254 .LP
 255 Large pages are required to be mapped at addresses that are multiples of the
 256 size of the large page. Given that the heap is typically not large page
 257 aligned, the starting portions of the heap (below the first large page aligned
 258 address) are mapped with the system memory page size. See
 259 \fBgetpagesize\fR(3C).
 260 .sp
 261 .LP
 262 To provide a heap that will be mapped with a large page size, an application
 263 can be built using a link-editor (\fBld\fR(1)) \fBmapfile\fR containing the
 264 \fBbss\fR segment declaration directive. Refer to the section Mapfile Option in
 265 the \fILinker and Libraries Guide\fR for more details of this directive and the
 266 template \fBmapfile\fR provided in \fB/usr/lib/ld/map.bssalign\fR. Users are
 267 cautioned that an alignment specification may be machine-specific and may lose
 268 its benefit on different hardware platforms. A more flexible means of
 269 requesting the most optimal underlying page size may evolve in future releases.
 270 .sp
 271 .LP
 272 \fBmpss.so.1\fR(1), a preloadable shared object, can also be used to set the
 273 preferred stack and/or heap page sizes.