path: root/usr/src/man/man1/ppgsz.1

'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH PPGSZ 1 "Jan 23, 2003"
.SH NAME
ppgsz \- set preferred page size for stack, heap, and/or other anonymous
segments
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/ppgsz\fR [\fB-F\fR] \fB-o\fR \fIoption\fR[,\fIoption\fR] \fIcmd\fR | \fB-p\fR \fIpid\fR...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBppgsz\fR utility sets the preferred page size for stack, heap, and/or
other anonymous segments for the target process(es), that is, the launched
\fIcmd\fR or the process(es) in the pid list. \fBppgsz\fR stops the target
process(es) while changing the page size. See \fBmemcntl\fR(2).
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 22n
Force. Sets the preferred page size options(s) for target process(es) even if
controlled by other process(es). Caution should be exercised when using the
\fB-F\fR flag. See \fBproc\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoption\fR[,\fIoption\fR]\fR
.ad
.RS 22n
The \fIoption\fRs are:
.sp
.ne 2
.na
\fB\fBheap\fR=\fIsize\fR\fR
.ad
.RS 14n
This option specifies the preferred page size for the heap of the target
process(es). \fBheap\fR is defined to be the bss (uninitialized data) and the
brk area that immediately follows the bss (see \fBbrk\fR(2)). The preferred
heap page size is set for the existing heap and for any additional heap memory
allocated in the future. See NOTES.
.RE

.sp
.ne 2
.na
\fB\fBstack\fR=\fIsize\fR\fR
.ad
.RS 14n
This option specifies the preferred page size for the stack of the target
process(es). The preferred stack page size is set for the existing stack and
newly allocated parts of the stack as it expands.
.RE

.sp
.ne 2
.na
\fB\fBanon\fR=\fIsize\fR\fR
.ad
.RS 14n
This option specifies the preferred page size for all existing
\fBMAP_PRIVATE\fR anonymous segments of the target process(es),  other than
\fBheap\fR and \fBstack\fR, which are large enough to fit at least one aligned
page of the specified size. For the segments that are large enough, the
preferred page size is set starting at the first size-aligned address in the
segment. The \fBanon\fR preferred pagesize is not applied to \fBMAP_PRIVATE\fR
anonymous segments created in the future. See \fBMAP_ANON\fR in \fBmmap\fR(2).
.sp
Anonymous memory refers to \fBMAP_PRIVATE\fR pages that are not directly
associated with a file in some filesystem. The \fBppgsz\fR command uses
\fBmemcntl\fR(2) to set the preferred page size for anonymous segments. See
\fBMC_HAT_ADVISE\fR in \fBmemcntl\fR(2).
.RE

At least one of the above options must be specified.
.sp
\fIsize\fR must be a supported page size (see \fBpagesize\fR(1)) or \fB0\fR, in
which case the system will select an appropriate page size. See
\fBmemcntl\fR(2).
.sp
\fIsize\fR defaults to bytes and can be specified in octal (\fB0\fR), decimal,
or hexadecimal (\fB0x\fR). The numeric value can be qualified with \fBK\fR,
\fBM\fR, \fBG\fR, or \fBT\fR to specify Kilobytes, Megabytes, Gigabytes, or
Terabytes, respectively. \fB4194304\fR, \fB0x400000\fR, \fB4096K\fR,
\fB0x1000K\fR, and \fB4M\fR are different ways to specify 4 Megabytes.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpid\fR\fR
.ad
.RS 22n
Sets the preferred page size option(s) for the target process(es) in the
process-id (\fIpid\fR) list following the \fB-p\fR option. The pid list can
also consist of names in the \fB/proc\fR directory. Only the process owner or
the super-user is permitted to set page size.
.sp
\fIcmd\fR is interpreted if \fB-p\fR is not specified. \fBppgsz\fR launches
\fIcmd\fR and applies page size option(s) to the new process.
.sp
The heap and stack preferred page sizes are inherited. Child process(es)
created (see \fBfork\fR(2)) from the launched process or the target process(es)
in the pid list after \fBppgsz\fR completes will inherit the preferred heap and
stack page sizes. The preferred page sizes of all segments are set back to the
default system page size on \fBexec\fR(2) (see \fBgetpagesize\fR(3C)). The
preferred page size for all other anonymous segments is not inherited by
children of the launched or target process(es).
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSetting the preferred heap and stack page size
.sp
.LP
The following example sets the preferred heap page size to \fB4M\fR and the
preferred stack page size to \fB512K\fR for all \fBora\fR\(emowned processes
running commands that begin with \fBora\fR:

.sp
.in +2
.nf
example% \fBppgsz -o heap=4M,stack=512K -p `pgrep -u ora '^ora'`\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRSetting the preferred anonymous page size
.sp
.LP
The following example sets the preferred page size of existing qualifying
anonymous segments to \fB512k\fR for process ID \fB953\fR:

.sp
.in +2
.nf
example% \fBppgsz -o anon=512k -p 953\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
If \fIcmd\fR is specified and successfully invoked (see \fBexec\fR(2)), the
exit status of \fBppgsz\fR will be the exit status of \fIcmd\fR. Otherwise,
\fBppgsz\fR will exit with one of the following values:
.sp
.ne 2
.na
\fB\fB0\fR \fR
.ad
.RS 7n
Successfully set preferred page size(s) for processes in the pid list.
.RE

.sp
.ne 2
.na
\fB\fB125\fR\fR
.ad
.RS 7n
An error occurred in \fBppgsz\fR. Errors include: invalid argument, invalid
page size(s) specified, and failure to set preferred page size(s) for one or
more processes in the pid list or \fIcmd\fR.
.RE

.sp
.ne 2
.na
\fB\fB126\fR\fR
.ad
.RS 7n
\fIcmd\fR was found but could not be invoked.
.RE

.sp
.ne 2
.na
\fB\fB127\fR\fR
.ad
.RS 7n
\fIcmd\fR could not be found.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/proc/*\fR \fR
.ad
.RS 29n
Process files.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/ld/map.bssalign\fR \fR
.ad
.RS 29n
A template link-editor \fBmapfile\fR for aligning bss (see NOTES).
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
.BR ld (1),
.BR mpss.so.1 (1),
.BR pagesize (1),
.BR pgrep (1),
.BR pmap (1),
.BR proc (1),
.BR brk (2),
.BR exec (2),
.BR fork (2),
.BR memcntl (2),
.BR mmap (2),
.BR sbrk (2),
.BR getpagesize (3C),
.BR proc (5),
.BR attributes (7)
.sp
.LP
\fILinker and Libraries Guide\fR
.SH NOTES
.sp
.LP
Due to resource constraints, the setting of the preferred page size does not
necessarily guarantee that the target process(es) will get the preferred page
size. Use \fBpmap\fR(1) to view the \fBactual\fR heap and stack page sizes of
the target process(es) (see \fBpmap\fR \fB-s\fR option).
.sp
.LP
Large pages are required to be mapped at addresses that are multiples of the
size of the large page. Given that the heap is typically not large page
aligned, the starting portions of the heap (below the first large page aligned
address) are mapped with the system memory page size. See
\fBgetpagesize\fR(3C).
.sp
.LP
To provide a heap that will be mapped with a large page size, an application
can be built using a link-editor (\fBld\fR(1)) \fBmapfile\fR containing the
\fBbss\fR segment declaration directive. Refer to the section Mapfile Option in
the \fILinker and Libraries Guide\fR for more details of this directive and the
template \fBmapfile\fR provided in \fB/usr/lib/ld/map.bssalign\fR. Users are
cautioned that an alignment specification may be machine-specific and may lose
its benefit on different hardware platforms. A more flexible means of
requesting the most optimal underlying page size may evolve in future releases.
.sp
.LP
\fBmpss.so.1\fR(1), a preloadable shared object, can also be used to set the
preferred stack and/or heap page sizes.