illumos: manual page: ppgsz.1

PPGSZ(1) User Commands PPGSZ(1)

NAME

ppgsz - set preferred page size for stack, heap, and/or other anonymous
segments

SYNOPSIS

/usr/bin/ppgsz [-F] -o option[,option] cmd | -p pid...

DESCRIPTION

The ppgsz utility sets the preferred page size for stack, heap, and/or
other anonymous segments for the target process(es), that is, the
launched cmd or the process(es) in the pid list. ppgsz stops the target
process(es) while changing the page size. See memcntl(2).

OPTIONS

The following options are supported:

-F
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 -F flag. See proc(1).

-o option[,option]
The options are:

heap=size
This option specifies the preferred
page size for the heap of the target
process(es). heap is defined to be
the bss (uninitialized data) and the
brk area that immediately follows the
bss (see brk(2)). The preferred heap
page size is set for the existing
heap and for any additional heap
memory allocated in the future. See
NOTES.

stack=size
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.

anon=size
This option specifies the preferred
page size for all existing
MAP_PRIVATE anonymous segments of the
target process(es), other than heap
and stack, 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 anon preferred pagesize is not
applied to MAP_PRIVATE anonymous
segments created in the future. See
MAP_ANON in mmap(2).

Anonymous memory refers to
MAP_PRIVATE pages that are not
directly associated with a file in
some filesystem. The ppgsz command
uses memcntl(2) to set the preferred
page size for anonymous segments. See
MC_HAT_ADVISE in memcntl(2).

At least one of the above options must be
specified.

size must be a supported page size (see
pagesize(1)) or 0, in which case the system will
select an appropriate page size. See memcntl(2).

size defaults to bytes and can be specified in
octal (0), decimal, or hexadecimal (0x). The
numeric value can be qualified with K, M, G, or T
to specify Kilobytes, Megabytes, Gigabytes, or
Terabytes, respectively. 4194304, 0x400000, 4096K,
0x1000K, and 4M are different ways to specify 4
Megabytes.

-p pid
Sets the preferred page size option(s) for the
target process(es) in the process-id (pid) list
following the -p option. The pid list can also
consist of names in the /proc directory. Only the
process owner or the super-user is permitted to set
page size.

cmd is interpreted if -p is not specified. ppgsz
launches cmd and applies page size option(s) to the
new process.

The heap and stack preferred page sizes are
inherited. Child process(es) created (see fork(2))
from the launched process or the target process(es)
in the pid list after ppgsz 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 exec(2) (see
getpagesize(3C)). The preferred page size for all
other anonymous segments is not inherited by
children of the launched or target process(es).

EXAMPLES

Example 1: Setting the preferred heap and stack page size

The following example sets the preferred heap page size to 4M and the
preferred stack page size to 512K for all ora--owned processes running
commands that begin with ora:

example% ppgsz -o heap=4M,stack=512K -p `pgrep -u ora '^ora'`

Example 2: Setting the preferred anonymous page size

The following example sets the preferred page size of existing qualifying
anonymous segments to 512k for process ID 953:

example% ppgsz -o anon=512k -p 953

EXIT STATUS

If cmd is specified and successfully invoked (see exec(2)), the exit
status of ppgsz will be the exit status of cmd. Otherwise, ppgsz will
exit with one of the following values:

0
Successfully set preferred page size(s) for processes in the pid
list.

125
An error occurred in ppgsz. 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 cmd.

126
cmd was found but could not be invoked.

127
cmd could not be found.

FILES

/proc/*
Process files.

/usr/lib/ld/map.bssalign
A template link-editor mapfile for aligning
bss (see NOTES).

ATTRIBUTES

NOTES

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 pmap(1) to view the actual heap and stack page
sizes of the target process(es) (see pmap -s option).

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
getpagesize(3C).

To provide a heap that will be mapped with a large page size, an
application can be built using a link-editor (ld(1)) mapfile containing
the bss segment declaration directive. Refer to the section Mapfile
Option in the Linker and Libraries Guide for more details of this
directive and the template mapfile provided in /usr/lib/ld/map.bssalign.
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.

mpss.so.1(1), a preloadable shared object, can also be used to set the
preferred stack and/or heap page sizes.

January 23, 2003 PPGSZ(1)