bionic (8) hugectl.8.gz

Provided by: hugepages_2.19-0ubuntu1_amd64 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.

       --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)