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 supports 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/Documentation/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  applications  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 environment. 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)