Add missing man pages for ld.hugetlbfs.1, hugetlbfs_find_path.3,
hugetlbfs_find_path_for_size.3, gethugepagesize.3, hugetlbfs_test_path.3,
hugetlbfs_unlinked_fd.3, and hugetlbfs_unlinked_fd_for_size.3. Add cross
references to the new man pages.
Fix some typos in gethugepagesizes.3, getpagesizes.3, and libhugetlbfs.7.
Document HUGETLB_DEFAULT_PAGE_SIZE.
Signed-off-by: Andrew Hastings <a...@cray.com> on behalf of Cray Inc.
---
-Andrew Hastings
Cray Inc.
diff -ruNp libhugetlbfs-2.13/Makefile libhugetlbfs-2.13-patched/Makefile
--- libhugetlbfs-2.13/Makefile 2012-03-05 07:20:12.000000000 -0600
+++ libhugetlbfs-2.13-patched/Makefile 2012-03-08 13:49:29.000178000 -0600
@@ -11,9 +11,10 @@ INSTALL_SCRIPT = cpupcstat oprofile_map_
INSTALL_HELPER = huge_page_setup_helper.py
INSTALL_PERLMOD = DataCollect.pm OpCollect.pm PerfCollect.pm Report.pm
INSTALL_HEADERS = hugetlbfs.h
-INSTALL_MAN1 = pagesize.1
-INSTALL_MAN3 = get_huge_pages.3 get_hugepage_region.3 \
- gethugepagesizes.3 getpagesizes.3
+INSTALL_MAN1 = ld.hugetlbfs.1 pagesize.1
+INSTALL_MAN3 = get_huge_pages.3 get_hugepage_region.3 gethugepagesize.3 \
+ gethugepagesizes.3 getpagesizes.3 hugetlbfs_find_path.3 \
+ hugetlbfs_test_path.3 hugetlbfs_unlinked_fd.3
INSTALL_MAN7 = libhugetlbfs.7
INSTALL_MAN8 = hugectl.8 hugeedit.8 hugeadm.8 cpupcstat.8
LDSCRIPT_TYPES = B BDT
@@ -392,8 +393,12 @@ install-man:
done
rm -f $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
rm -f $(DESTDIR)$(MANDIR3)/free_hugepage_region.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
ln -s get_huge_pages.3.gz $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
ln -s get_hugepage_region.3.gz
$(DESTDIR)$(MANDIR3)/free_hugepage_region.3.gz
+ ln -s hugetlbfs_unlinked_fd.3.gz
$(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
+ ln -s hugetlbfs_find_path.3.gz
$(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
for x in $(INSTALL_MAN7); do \
$(INSTALL) -m 444 man/$$x $(DESTDIR)$(MANDIR7); \
gzip -f $(DESTDIR)$(MANDIR7)/$$x; \
diff -ruNp libhugetlbfs-2.13/man/gethugepagesize.3
libhugetlbfs-2.13-patched/man/gethugepagesize.3
--- libhugetlbfs-2.13/man/gethugepagesize.3 1969-12-31 18:00:00.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/gethugepagesize.3 2012-03-08
13:46:34.000030000 -0600
@@ -0,0 +1,54 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH GETHUGEPAGESIZE 3 "March 7, 2012"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+gethugepagesize - Get the default huge page size
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+
+.B long gethugepagesize(void)
+
+.SH DESCRIPTION
+
+The gethugepagesize() function returns the default huge page size used by
+libhugetlbfs. This will be either the system default, or a valid value set
+by the environment variable \fBHUGETLB_DEFAULT_PAGE_SIZE\fP.
+
+If the system does not support any huge page sizes an error is returned.
+
+.SH RETURN VALUE
+
+On success, the default huge page size is returned. On failure,
+-1 is returned and errno is set appropriately.
+
+.SH ERRORS
+
+.TP
+.B ENOSYS
+The system does not support huge pages.
+
+.SH SEE ALSO
+.I libhugetlbfs(7)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff -ruNp libhugetlbfs-2.13/man/gethugepagesizes.3
libhugetlbfs-2.13-patched/man/gethugepagesizes.3
--- libhugetlbfs-2.13/man/gethugepagesizes.3 2012-03-05 07:20:12.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/gethugepagesizes.3 2012-03-08
13:46:34.000046000 -0600
@@ -19,7 +19,6 @@
gethugepagesizes - Get the system supported huge page sizes
.SH SYNOPSIS
.B #include <hugetlbfs.h>
-.br
.br
int gethugepagesizes(long pagesizes[], int n_elem);
@@ -41,12 +40,10 @@ the number of huge page sizes stored in
.SH ERRORS
.TP
-.B ERRNO
+.B EINVAL
\fBn_elem\fP is less than zero or \fBn_elem\fP is greater than zero and
\fBpagesizes\fP is NULL.
-
.PP
-
Also see opendir(3) for other possible values for errno. This error occurs
when the sysfs directory exists but cannot be opened.
@@ -61,9 +58,9 @@ specific size to see if a mount point is
.SH SEE ALSO
.I oprofile(1),
.I opendir(3),
+.I hugetlbfs_find_path_for_size(3),
.I libhugetlbfs(7)
.SH AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel
mailing list.
-
diff -ruNp libhugetlbfs-2.13/man/getpagesizes.3
libhugetlbfs-2.13-patched/man/getpagesizes.3
--- libhugetlbfs-2.13/man/getpagesizes.3 2012-03-05 07:20:12.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/getpagesizes.3 2012-03-08
13:46:34.000062000 -0600
@@ -41,7 +41,7 @@ number of page sizes stored in \fBpagesi
.SH ERRORS
.TP
-.B ERRNO
+.B EINVAL
\fBn_elem\fP is less than zero or \fBn_elem\fP is greater than zero and
\fBpagesizes\fP is NULL.
diff -ruNp libhugetlbfs-2.13/man/hugetlbfs_find_path.3
libhugetlbfs-2.13-patched/man/hugetlbfs_find_path.3
--- libhugetlbfs-2.13/man/hugetlbfs_find_path.3 1969-12-31 18:00:00.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/hugetlbfs_find_path.3 2012-03-08
13:46:34.000071000 -0600
@@ -0,0 +1,52 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH HUGETLBFS_FIND_PATH 3 "March 7, 2012"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+hugetlbfs_find_path, hugetlbfs_find_path_for_size - Locate an appropriate
hugetlbfs mount point
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+
+.br
+const char *hugetlbfs_find_path(void);
+.br
+const char *hugetlbfs_find_path_for_size(long page_size);
+
+.SH DESCRIPTION
+
+These functions return a pathname for a mounted hugetlbfs filesystem for
+the appropriate huge page size. For hugetlbfs_find_path, the default
+huge page size is used (see gethugepagesize(3)). For
+hugetlbfs_find_path_for_size, a valid huge page size must be specified
+(see gethugepagesizes(3)).
+
+.SH RETURN VALUE
+
+On success, a non-NULL value is returned.
+On failure, NULL is returned.
+
+.SH SEE ALSO
+.I libhugetlbfs(7),
+.I gethugepagesize(3),
+.I gethugepagesizes(3)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff -ruNp libhugetlbfs-2.13/man/hugetlbfs_test_path.3
libhugetlbfs-2.13-patched/man/hugetlbfs_test_path.3
--- libhugetlbfs-2.13/man/hugetlbfs_test_path.3 1969-12-31 18:00:00.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/hugetlbfs_test_path.3 2012-03-08
13:46:34.000079000 -0600
@@ -0,0 +1,53 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH HUGETLBFS_TEST_PATH 3 "March 7, 2012"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+hugetlbfs_test_path - Determine whether a mount point is hugetlbfs
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+
+.br
+int hugetlbfs_test_path(const char *mount);
+
+.SH DESCRIPTION
+
+The hugetlbfs_test_path() function determines whether a given pathname
+is in a hugetlbfs filesystem.
+
+.SH RETURN VALUE
+
+On success, 1 is returned for a hugetlbfs filesystem, or 0 for a
+non-hugetlbfs filesystem. On failure, -1 is returned and errno is set
+appropriately.
+
+.SH ERRORS
+
+.PP
+Please see statfs(3) for possible values for errno.
+
+
+.SH SEE ALSO
+.I statfs(3),
+.I libhugetlbfs(7)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff -ruNp libhugetlbfs-2.13/man/hugetlbfs_unlinked_fd.3
libhugetlbfs-2.13-patched/man/hugetlbfs_unlinked_fd.3
--- libhugetlbfs-2.13/man/hugetlbfs_unlinked_fd.3 1969-12-31
18:00:00.000000000 -0600
+++ libhugetlbfs-2.13-patched/man/hugetlbfs_unlinked_fd.3 2012-03-08
13:46:34.000087000 -0600
@@ -0,0 +1,55 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH HUGETLBFS_UNLINKED_FD 3 "March 7, 2012"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+hugetlbfs_unlinked_fd, hugetlbfs_unlinked_fd_for_size - Obtain a file
descriptor for a new unlinked file in hugetlbfs
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+
+.br
+.B int hugetlbfs_unlinked_fd(void);
+.br
+.B int hugetlbfs_unlinked_fd_for_size(long page_size);
+
+.SH DESCRIPTION
+
+These functions return an open file descriptor for a unique, newly-created
+file in a hugetlbfs filesystem. To avoid leaking hugepages, the file
+is unlinked automatically before the function returns.
+
+For hugetlbfs_unlinked_fd, the default huge page size is used (see
+gethugepagesize(3)). For hugetlbfs_unlinked_fd_for_size, a valid huge
+page size must be specified (see gethugepagesizes(3)).
+
+.SH RETURN VALUE
+
+On success, a valid open file descriptor is returned. On failure,
+-1 is returned and errno may be set appropriately.
+
+.SH SEE ALSO
+.I gethugepagesize(3),
+.I gethugepagesizes(3),
+.I mkstemp(3),
+.I libhugetlbfs(7)
+
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff -ruNp libhugetlbfs-2.13/man/ld.hugetlbfs.1
libhugetlbfs-2.13-patched/man/ld.hugetlbfs.1
--- libhugetlbfs-2.13/man/ld.hugetlbfs.1 1969-12-31 18:00:00.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/ld.hugetlbfs.1 2012-03-08
13:46:34.000095000 -0600
@@ -0,0 +1,72 @@
+\" Hey, EMACS: -*- nroff -*-
+.\" Copyright 2012 Cray Inc.
+.\" All rights reserved.
+.\" Licensed under LGPL 2.1 by Cray Inc.
+.\"
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH LD.HUGETLBFS 1 "March 12, 2012"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+ld.hugetlbfs \- link a program for huge pages
+.SH SYNOPSIS
+.B ld.hugetlbfs [options]
+.SH DESCRIPTION
+
+\fBld.hugetlbfs\fP replaces the normal \fBld\fP command for linking programs
+to use hugepages. Under gcc, you should use the option
+\fB-B /usr/share/libhugetlbfs\fP which tells gcc to look in a non-standard
+location for the linker. This could be set in the \fBCFLAGS\fP environment
+variable.
+
+.TP
+.B -Wl,--hugetlbfs-align
+
+This method of linking an application permits greater flexibility at runtime.
+Using HUGETLB_ELFMAP, it is possible to control which program segments are
+placed in hugepages. The following four settings will cause the indicated
+segments to be placed in hugepages:
+
+ HUGETLB_ELFMAP=R Read-only segments (text)
+ HUGETLB_ELFMAP=W Writable segments (data/BSS)
+ HUGETLB_ELFMAP=RW All segments (text/data/BSS)
+ HUGETLB_ELFMAP=no No segments
+
+It is possible to select specific huge page sizes for read-only and writable
+segments by using the following advanced syntax:
+
+ HUGETLB_ELFMAP=[R[=<pagesize>]:[W[=<pagesize>]]
+
+.B -Wl,--hugetlbfs-link=B
+
+Under binutils 2.16 or older, this option will link the application to store
+BSS data (only) into hugepages.
+
+.B -Wl,--hugetlbfs-link=BDT
+
+Under binutils 2.16 or older, this option will link the application to store
+text, initialized data and BSS data into hugepages.
+
+.SH FILES
+[DESTDIR|/usr/share]/doc/libhugetlbfs/HOWTO
+
+.SH SEE ALSO
+.I libhugetlbfs(7),
+.I hugectl(8),
+.I hugeedit(8)
+.br
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
diff -ruNp libhugetlbfs-2.13/man/libhugetlbfs.7
libhugetlbfs-2.13-patched/man/libhugetlbfs.7
--- libhugetlbfs-2.13/man/libhugetlbfs.7 2012-03-05 07:20:12.000000000
-0600
+++ libhugetlbfs-2.13-patched/man/libhugetlbfs.7 2012-03-08
13:46:34.000111000 -0600
@@ -39,8 +39,8 @@ 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.
+but no pre-loading is required. See /usr/share/doc/libhugetlbfs/HOWTO and
+ld.hugetlbfs(1) for detailed instructions on relinking applications.
For applications that are hugepage-aware and linked to the library
\fBget_huge_pages()\fP can be used for the direct allocation of
@@ -64,6 +64,11 @@ all cases, the environment being unset i
disabled.
.TP
+.B HUGETLB_DEFAULT_PAGE_SIZE=<pagesize>
+This sets the default hugepage size to be used by libhugetlbfs. If not
+set, libhugetlbfs will use the kernel's default hugepage size.
+
+.TP
.B 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
@@ -199,14 +204,27 @@ The default value for this is 1 and the
Once set, this will give very detailed output on what is happening in the
library and run extra diagnostics.
+.SH FILES
+[DESTDIR|/usr/share]/doc/libhugetlbfs/HOWTO
+
.SH SEE ALSO
.I oprofile(1),
+.I ld.hugetlbfs(1),
.I hugectl(8),
.I hugeedit(8),
+.I gethugepagesize(3),
+.I gethugepagesizes(3),
+.I getpagesizes(3),
+.I hugetlbfs_test_path(3),
+.I hugetlbfs_find_path(3),
+.I hugetlbfs_find_path_for_size(3),
+.I hugetlbfs_test_path(3),
+.I hugetlbfs_test_path_for_size(3),
+.I hugetlbfs_unlinked_fd(3),
+.I hugetlbfs_unlinked_fd_for_size(3),
.I get_huge_pages(3),
.I free_huge_pages(3)
.br
.SH AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel
mailing list.
-
------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/
_______________________________________________
Libhugetlbfs-devel mailing list
Libhugetlbfs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/libhugetlbfs-devel
