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). Cau-
                               tion 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 speci-
                                   fied 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 run-
       ning 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

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWesu (32-bit)             |
       +-----------------------------+-----------------------------+
       |                             |SUNWesxu (64-bit)            |
       +-----------------------------+-----------------------------+
       |Interface Stability          |Evolving                     |
       +-----------------------------+-----------------------------+

SEE ALSO

       ld(1), mpss.so.1(1), pagesize(1), pgrep(1), pmap(1), proc(1), brk(2), exec(2),  fork(2),  memcntl(2),  mmap(2),  sbrk(2),  getpagesize(3C),
       proc(4), attributes(5)

       Linker and Libraries Guide

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.

SunOS 5.10                                                          23 Jan 2003                                                           ppgsz(1)