Provided by: hugepages_2.11-0ubuntu1_i386 bug

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.

       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)