This patch adds manual pages for the path-related functions
hugetlbfs_test_path(), hugetlbfs_find_path() and hugetlbfs_unlinked_fd()
and their size-equivalents where they exist. The functions dealing with
the default hugepage size have existed since libhugetlbfs 1.0 but were not
documented.
Of these functions, the most interesting one is hugetlbfs_unlinked_fd().
It can be trivially used to create multiple memory regions that grow/shrink
with mmap() or are placed in a specific location in memory. This may be
important for custom allocators that need more control over the created
memory region than provided by the easier-to-use function get_huge_pages().
Signed-off-by: Mel Gorman <[EMAIL PROTECTED]>
---
Makefile | 8 +++++-
man/gethugepagesizes.3 | 8 ++++-
man/hugetlbfs_find_path.3 | 50 +++++++++++++++++++++++++++++++++++++++
man/hugetlbfs_test_path.3 | 39 ++++++++++++++++++++++++++++++
man/hugetlbfs_unlinked_fd.3 | 55 +++++++++++++++++++++++++++++++++++++++++++
5 files changed, 157 insertions(+), 3 deletions(-)
create mode 100644 man/hugetlbfs_find_path.3
create mode 100644 man/hugetlbfs_test_path.3
create mode 100644 man/hugetlbfs_unlinked_fd.3
diff --git a/Makefile b/Makefile
index 4554154..9894351 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,9 @@ BIN_OBJ_DIR=obj
INSTALL_BIN = hugectl hugeedit hugeadm pagesize
INSTALL_HEADERS = hugetlbfs.h
INSTALL_MAN1 = pagesize.1
-INSTALL_MAN3 = get_huge_pages.3 gethugepagesizes.3 getpagesizes.3
+INSTALL_MAN3 = get_huge_pages.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
LDSCRIPT_TYPES = B BDT
@@ -379,7 +381,11 @@ install-man:
gzip -f $(DESTDIR)$(MANDIR3)/$$x; \
done
rm -f $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
+ rm -f $(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
ln -s get_huge_pages.3.gz $(DESTDIR)$(MANDIR3)/free_huge_pages.3.gz
+ ln -s hugetlbfs_find_path.3.gz
$(DESTDIR)$(MANDIR3)/hugetlbfs_find_path_for_size.3.gz
+ ln -s hugetlbfs_unlinked_fd.3.gz
$(DESTDIR)$(MANDIR3)/hugetlbfs_unlinked_fd_for_size.3.gz
for x in $(INSTALL_MAN7); do \
$(INSTALL) -m 444 man/$$x $(DESTDIR)$(MANDIR7); \
gzip -f $(DESTDIR)$(MANDIR7)/$$x; \
diff --git a/man/gethugepagesizes.3 b/man/gethugepagesizes.3
index 02442a9..64fb6c6 100644
--- a/man/gethugepagesizes.3
+++ b/man/gethugepagesizes.3
@@ -59,8 +59,12 @@ by \fBlibhugetlbfs\fP, hugetlbfs_find_path_for_size() can be
called on a
specific size to see if a mount point is configured.
.SH SEE ALSO
-.I oprofile(1),
-.I opendir(3),
+.I oprofile(1)
+,
+.I opendir(3)
+,
+.I hugetlbfs_find_path_for_size(3)
+,
.I libhugetlbfs(7)
.SH AUTHORS
diff --git a/man/hugetlbfs_find_path.3 b/man/hugetlbfs_find_path.3
new file mode 100644
index 0000000..e4cd809
--- /dev/null
+++ b/man/hugetlbfs_find_path.3
@@ -0,0 +1,50 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" 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_FOR_SIZE 3 "November 6, 2008"
+.\" 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_for_size \- Locate a mount point for hugetlbfs supporting
a given pagesize
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+.B const char *hugetlbfs_find_path(void);
+.br
+.B const char *hugetlbfs_find_path_for_size(long page_size);
+.SH DESCRIPTION
+
+\fBhugetlbfs_find_path\fB and its page-size-aware companion
+\fBhugetlb_find_path_for_size() locate a hugetlbfs mount point for the
+default hugepage size and a given \fBpage_size\fB respectively. Multiple
+hugetlbfs mounts may exist as a single mount point cannot mix huge page
+sizes at time of writing.
+
+If there are multiple mount points for a pagesize, this function returns the
+first one found. This is a limitation of hugetlbfs where it only tracks one
+mount per pagesize. This may be a problem on systems that have per-application
+mount points.
+
+.SH RETURN VALUE
+
+A path to a mount point if one is found and NULL otherwise.
+
+.SH SEE ALSO
+.I libhugetlbfs(7)
+,
+.I mount(8)
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
+
diff --git a/man/hugetlbfs_test_path.3 b/man/hugetlbfs_test_path.3
new file mode 100644
index 0000000..9a9236e
--- /dev/null
+++ b/man/hugetlbfs_test_path.3
@@ -0,0 +1,39 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" 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 "November 2006, 2008"
+.\" 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 - Detect if a path is within a hugetlbfs mount
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+.B int hugetlbfs_test_path(const char *path)
+.SH DESCRIPTION
+
+\fBhugetlbfs_test_path()\fB detects if a given \fBpath\fB is within a
+hugetlbfs filesystem or not.
+
+.SH RETURN VALUE
+
+A non-zero value is returned if the path is on a hugetlbfs filesystem and
+0 otherwise.
+
+.SH SEE ALSO
+.I libhugetlbfs(7)
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
+
diff --git a/man/hugetlbfs_unlinked_fd.3 b/man/hugetlbfs_unlinked_fd.3
new file mode 100644
index 0000000..3dbd91b
--- /dev/null
+++ b/man/hugetlbfs_unlinked_fd.3
@@ -0,0 +1,55 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" 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 "November 6, 2008"
+.\" 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 \- Open an unlinked file
on a hugetlbfs filesystem
+.SH SYNOPSIS
+.B #include <hugetlbfs.h>
+.br
+
+.br
+.B int hugetlbfs_unlinked_fd(void);
+.br
+.B hugetlbfs_unlinked_fd_for_size(long page_size);
+.SH DESCRIPTION
+
+\fBhugetlbfs_unlinked_fd()\fB and its page-size-aware companion
+\fBhugetlbfs_unlinked_fd_for_size()\fB discover a suitable hugetlbfs mount
+point, open a file, unlink it and return the descriptor. This is mainly used
+interally by hugetlbfs to create memory regions with map(). An example usage
+might be to create a heap by allocating and unlinked filedescriptor and using
+mmap() and munmap to grow and shrink the heap respectively.
+
+.SH RETURN VALUE
+
+Both functions return a valid file descriptor on success and -1 on failure.
+errno is not necessarily set to anything useful when an error occurs.
+
+.SH NOTES
+
+In the current version of libhugetlbfs, it is difficult to programatically
+determine why an unlinked file could not be created. It will depend on the
+user reading messages writting to console to diagnose and correct the error.
+
+.SH SEE ALSO
+.I oprofile(1)
+,
+.I libhugetlbfs(7)
+.SH AUTHORS
+libhugetlbfs was written by various people on the libhugetlbfs-devel
+mailing list.
+
--
1.5.6.5
--
Mel Gorman
Part-time Phd Student Linux Technology Center
University of Limerick IBM Dublin Software Lab
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Libhugetlbfs-devel mailing list
Libhugetlbfs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/libhugetlbfs-devel
