Provided by: libhugetlbfs0_2.11-0ubuntu1_i386 bug

NAME

       libhugetlbfs  -  preload library to back text, data, malloc() or shared
       memory with hugepages

SYNOPSIS

       export [environment options]
       [LD_PRELOAD=libhugetlbfs.so] target_application

DESCRIPTION

       libhugetlbfs is  a  library  that  can  back  application  text,  data,
       malloc()  and  shared  memory  with  hugepages.  This  is of benefit to
       applications that use large amounts  of  address  space  and  suffer  a
       performance  hit  due to TLB misses. Wall-clock time or oprofile can be
       used to  determine  if  there  is  a  performance  benefit  from  using
       libhugetlbfs or not.  In all cases but shared memory, a hugetlbfs mount
       must exist and a hugepage pool defined for hugepages to be used.

       Some limited functionality  is  available  for  unmodified  dynamically
       linked  applications.  By  preloading the library, the library can back
       malloc() and shared memory, and text and data segments can be partially
       backed if they are large enough.

       For  the  effective  backing  of  text  and  data  with huge pages, the
       application must  be  linked  to  the  library  and  the  ELF  segments
       correctly  aligned  using the ld helpers. Once linked, malloc or shared
       memory can  still  be  backed  but  no  pre-loading  is  required.  See
       /usr/share/docs/libhugetlbfs/HOWTO   for   detailed   instructions   on
       relinking applications.

       For applications that are hugepage-aware  and  linked  to  the  library
       get_huge_pages()  can  be  used  for the direct allocation of hugepage-
       backed regions.

       Unless otherwise specified, libhugetlbfs will use the default  hugepage
       size  to  back  memory  regions.  The  default  size  is  the  value of
       Hugepagesize displayed in /proc/meminfo. The size can be  specified  in
       bytes  or in kilobytes, megabytes, or gigabytes by appending K, M, or G
       respectively. It is an error to  specify  a  invalid,  unsupported,  or
       otherwise  unconfigured  huge  page  size.  Kernel  2.6.27  or later is
       required to specify any pagesize other than the default.

       See /usr/share/docs/libhugetlbfs/HOWTO for detailed instructions on how
       the   library   should   be   used,  particularly  when  relinking  the
       application.  This  manual  page  provides  a  brief  synopsis  of  the
       environment variables as a quick reference.

       The  following  variables  affect  what  memory  regions  are backed by
       hugepages. In all  cases,  the  environment  being  unset  implies  the
       feature should remain disabled.

       HUGETLB_MORECORE=[yes|<pagesize>]
              This   enables   the   hugepage  malloc()  feature,  instructing
              libhugetlbfs to override glibc's normal morecore() function with
              a  hugepage  version  and  use it for malloc().  All application
              malloc() memory should come from hugepage memory until  it  runs
              out,   it   will   then  fallback  to  base  pages.   Note  that
              applications that use custom allocators may not be able to  back
              their  heaps  using  hugepages and this environment variable. It
              may  be  necessary  to  modify  the  custom  allocator  to   use
              get_huge_pages().

       HUGETLB_SHM=yes
              When  this  environment variable is set, the SHM_HUGETLB flag is
              added to the shmget() call and the size parameter is aligned  to
              back  the  shared  memory  segment  with hugepages. In the event
              hugepages cannot be used, base pages will be used instead and  a
              warning  will  be  printed  to explain the failure. The pagesize
              cannot be specified with this parameter. To change  the  kernels
              default  hugepage  size, use the pagesize= kernel boot parameter
              (2.6.26 or later required).

       HUGETLB_ELFMAP=[no|[R[<=pagesize>]:[W[<=pagesize>]]]
              If  the  application  has  been  relinked  (see  the  HOWTO  for
              instructions),  this  environment  variable  determines  whether
              read-only,  read-write,  both  or  no  segments  are  backed  by
              hugepages  and  what pagesize should be used. If the recommended
              relinking method has been used, then hugeedit  can  be  used  to
              automatically back the text or data by default.

       HUGETLB_FORCE_ELFMAP=yes
              Force  the  use  of hugepages for text and data segments even if
              the application has not been relinked to align the ELF  segments
              on  a  hugepage  boundary.   Partial  segment  remapping  is not
              guaranteed to work and the segments  must  be  large  enough  to
              contain at least one hugepage for the remapping to occur.

       The following options affect how libhugetlbfs behaves.

       HUGETLB_MORECORE_SHRINK=yes
              By  default,  the  hugepage  heap  does not shrink. Shrinking is
              enabled by setting this environment variable. It is disabled  by
              default  as  glibc occasionally exhibits strange behaviour if it
              mistakes the heap returned by libhugetlbfs as a foreign brk().

       HUGETLB_NO_PREFAULT
              By default libhugetlbfs will  prefault  regions  it  creates  to
              ensure  they  can  be referenced without receiving a SIGKILL. On
              kernels older than 2.6.27, this was necessary as the system  did
              not guarantee that future faults would succeed on regions mapped
              MAP_PRIVATE.  Prefaulting impacts the  performance  of  malloc()
              and can result in poor placement on NUMA systems. If it is known
              the hugepage pool is large enough to run the application or  the
              kernel  is  2.6.27 or later, this environment variable should be
              set.

       HUGETLB_NO_RESERVE=yes

              By default, the kernel will reserve huge pages at mmap() time to
              ensure  that  future faults will succeed. This avoids unexpected
              application failure at fault time but some  applications  depend
              on  memory  overcommit to create large sparse mappings. For this
              type of application,  setting  this  environment  variable  will
              create huge page backed mappings without a reservation. Use this
              option with extreme care as in the  event  huge  pages  are  not
              available  when  the  mapping  is  used, the application will be
              killed. On older kernels, the use of this  feature  can  trigger
              the OOM killer. Hence, even with this variable set, reservations
              may still be used for safety.

       HUGETLB_MORECORE_HEAPBASE=address
              libhugetlbfs normally picks an address to use as the base of the
              heap for malloc() automatically. This environment variable fixes
              which address is used.

       HUGETLB_PATH=<path>
              The path to the hugetlbfs mount is automatically  determined  at
              run-time.  In  the event there are multiple mounts and the wrong
              one is being selected, use this option  to  select  the  correct
              one.  This may be the case if an application-specific mount with
              a fixed quota has been created for example.

       HUGETLB_SHARE=1
              By default, libhugetlbfs uses unlinked hugetlbfs files to  store
              remapped  program  segment  data. If the same program is started
              multiple times using hugepage segments, multiple hugepages  will
              be used to store the same program data. The reduce this wastage,
              setting this environment variable will share read-only  segments
              between  multiple  invocations  of  a program at the cost of the
              memory being used whether the applications are running  or  not.
              It  is also possible that a malicious application inferfere with
              other applications executable  code.  See  the  HOWTO  for  more
              detailed information on this topic.

       The following options control the verbosity of libhugetlbfs.

       HUGETLB_VERBOSE=<level>
              The  default  value  for this is 1 and the range of the value is
              from 0 to 99. The higher the value, the more verbose the  output
              is. 0 is quiet and 3 will output much debugging information.

       HUGETLB_DEBUG
              Once  set,  this  will  give  very  detailed  output  on what is
              happening in the library and run extra diagnostics.

SEE ALSO

       oprofile(1),      hugectl(8),      hugeedit(8),      get_huge_pages(3),
       free_huge_pages(3)

AUTHORS

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

                              September 27, 2008               LIBHUGETLBFS(7)