HUGECTL(8)						      System Manager's Manual							HUGECTL(8)

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 regions with hugepages. The use of hugepages benefit applications that use
       large amounts of address space and suffer a performance hit due to TLB misses.  Policy is enforced by libhugetlbfs and  hugectl	configures
       the environment based on the options provided.  Wall-clock time or oprofile can be used to determine if there is a performance benefit from
       using hugepages or not.

       To effectively back text/data, the target process must be relinked to align the ELF segments on a hugepage boundary. The library also  sup-
       ports  more  options  for  the control of memory regions than are exposed by the hugectl utility. 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 pages of the specified size.	To be effective, the process  must
	      be  relinked  as	described  in  the  HOWTO  to  align  the  ELF	segments.   It	is  possible  to partially back segments using the
	      HUGETLB_FORCE_ELMAP environment variable as described in the libhugetlbfs manual page.

       --heap[=<size>]
	      Use the glibc morecore hook to back malloc() with hugepages, optionally with pages of the specified size.  Note that this  does  not
	      affect  brk()  segments  and  applications that use custom allocators potentially do not use hugepages for their heap even with this
	      option specified.

       --shm  This option overrides shmget() to back shared memory regions with hugepages if possible. Segment size requests will  be  aligned	to
	      fit to the default hugepage size region.

       --share-text
	      Request  that  multiple application instances share text segments that are backed with huge pages.  This option sets the environment
	      variable HUGETLB_SHARE to 1.

       --thp  Align heap regions to huge page size for promotion by khugepaged.  For more information on transparent huge pages see linux-2.6/Doc-
	      umentation/transhuge.txt

       The following options affect how hugectl behaves.

       --no-preload
	      Disable  any  pre-loading  of  the libhugetlbfs library. This may be necessary if only the heap is being backed by hugepages and the
	      application is already linked against the library. hugectl may pre-load the library by mistake and this option prevents that.

       --force-preload
	      Force pre-loading of the libhugetlbfs library. This option is used when the segments of the  binary  are	aligned  to  the  hugepage
	      boundary of interest but the binary is not linked against libhugetlbfs. This is useful on PPC64 where binaries are aligned to 64K as
	      required by the ABI and the kernel is using a 4K base pagesize.

       --no-reserve
	      By default, huge pages are reserved at mmap() time so future faults will succeed. This avoids unexpected application but some appli-
	      cations depend on memory overcommit to create large sparse mappings. For this type of application, this switch will create huge page
	      backed mappings without a reservation if the kernel is recent enough to make this operation safe.  Use this option with extreme care
	      as in the event huge pages are not available when the mapping is faulted, the application will be killed.

       --dry-run
	      Instead of running the process, the hugectl utility will describe what environment variables it set for libhugetlbfs. This is useful
	      if additional environment variables are to be set and a launcher shell script is being developed.

       --library-use-path
	      By default, hugectl will use the version of libhugetlbfs it was installed with, even if this is not in the LD_LIBRARY_PATH  environ-
	      ment. Using this option forces hugectl to use the version of libhugetlbfs installed in the library system path.

       --library-path <path>
	      This option forces hugectl to use the libhugetlbfs libraries within the 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 can be set with --verbose from 0 to 99. The higher the
	      value, the more verbose the library will be. 0 is quiet and 3 will  output  much	debugging  information.  The  verbosity  level	is
	      increased by one each time -v is specified.

       -q     The -q option will drecease the verbosity level by 1 each time it is specified to a minimum of 0.

SEE ALSO

       oprofile(1), hugeadm(7), libhugetlbfs(7)

AUTHORS

       libhugetlbfs was written by various people on the libhugetlbfs-devel mailing list.

								 October 10, 2008							HUGECTL(8)