MAN page from Fedora 9 libhugetlbfs-utils-2.2-1.fc9.i386.rpm

HUGECTL

Section: Maintenance Commands (8)
Updated: October 10, 2008
Index

NAME

hugectl - Control policy for backing text, data and malloc() with hugepages

SYNOPSIS

hugectl [options] command {arguments}

DESCRIPTION

hugectl runs processes with a specific policy for backing memory regionswith hugepages. The use of hugepages benefit applications that use largeamounts of address space and suffer a performance hit due to TLB misses.Policy is enforced by libhugetlbfs and hugectl configures theenvironment based on the options provided. Wall-clock time or oprofile canbe used to determine if there is a performance benefit from using hugepagesor not.

To effectively back text/data, the target process must be relinked to alignthe ELF segments on a hugepage boundary. The library also supports more optionsfor the control of memory regions than are exposed by the hugectlutility. See the libhugetlbfs manual page for more details.

The following options affect what memory regions are backed by hugepages.

--text[=<size>],--data[=<size>],--bss[=<size>]: Back the text, data or BSS segments with hugepages, optionally with pagesof the specified size. To be effective, the process must be relinkedas described in the HOWTO to align the ELF segments. It is possible topartially back segments using the HUGETLB_FORCE_ELMAP environment variableas described in the libhugetlbfs manual page.
--heap[=<size>]: Use the glibc morecore hook to back malloc() with hugepages, optionallywith pages of the specified size. Note that this does not affect brk()segments and applications that use custom allocators potentially do notuse hugepages for their heap even with this option specified.
--shm: This option overrides shmget() to back shared memory regions with hugepagesif possible. Segment size requests will be aligned to fit to the defaulthugepage size region.
--share-text: Request that multiple application instances share text segments that arebacked with huge pages. This option sets the environment variableHUGETLB_SHARE to 1.

The following options affect how hugectl behaves.

--no-preload: Disable any pre-loading of the libhugetlbfs library. This may be necessaryif only the heap is being backed by hugepages and the application is alreadylinked against the library. hugectl may pre-load the library by mistakeand this option prevents that.
--dry-run: Instead of running the process, the hugectl utility will describe whatenvironment variables it set for libhugetlbfs. This is useful ifadditional environment variables are to be set and a launcher shell script isbeing developed.
--library-use-path: By default, hugectl will use the version of libhugetlbfs it wasinstalled with, even if this is not in the LD_LIBRARY_PATH environment. Usingthis option forces hugectl to use the version of libhugetlbfsinstalled in the library system path.
--library-path <path>: This option forces hugectl to use the libhugetlbfs libraries withinthe given prefix.

The following options affect the verbosity of libhugetlbfs.

--verbose <level>, -v: The default value for the verbosity level is 1 and the range of the value canbe set with --verbose from 0 to 99. The higher the value, the more verbose thelibrary will be. 0 is quiet and 3 will output much debugging information. Theverbosity level is increased by one each time -v is specified.

AUTHORS

libhugetlbfs was written by various people on the libhugetlbfs-develmailing list.

This document was created byman2html,using the manual pages.