# HG changeset patch
# User Bruno Haible <bruno@clisp.org>
# Date 1322263483 -3600
# Node ID d2f39a0d2549f88a04a8631ccf8d2cd23a6b8aba
# Parent  ff91f9a6096725fbae83c4f851a4c2c00cfa6528
pagealign_alloc: Doc and comments.

* doc/posix-functions/posix_memalign.texi: Refer to the pagealign_alloc
module.
* lib/pagealign_alloc.c (pagealign_alloc): Add comment.

diff --git a/ChangeLog b/ChangeLog
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2011-11-25  Bruno Haible  <bruno@clisp.org>
+
+	pagealign_alloc: Doc and comments.
+	* doc/posix-functions/posix_memalign.texi: Refer to the pagealign_alloc
+	module.
+	* lib/pagealign_alloc.c (pagealign_alloc): Add comment.
+
 2011-11-25  Jim Meyering  <meyering@redhat.com>
 
 	test-update-copyright.sh: avoid false-positive failure
diff --git a/doc/posix-functions/posix_memalign.texi b/doc/posix-functions/posix_memalign.texi
--- a/doc/posix-functions/posix_memalign.texi
+++ b/doc/posix-functions/posix_memalign.texi
@@ -17,3 +17,6 @@
 MacOS X 10.5, FreeBSD 6.0, NetBSD 3.0, OpenBSD 3.8, Minix 3.1.8, AIX 5.1, HP-UX 11,
 IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin 1.5.x, mingw, MSVC 9, Interix 3.5, BeOS.
 @end itemize
+
+The Gnulib module @code{pagealign_alloc} provides a similar API
+that returns memory aligned on a system page boundary.
diff --git a/lib/pagealign_alloc.c b/lib/pagealign_alloc.c
--- a/lib/pagealign_alloc.c
+++ b/lib/pagealign_alloc.c
@@ -123,6 +123,9 @@
 pagealign_alloc (size_t size)
 {
   void *ret;
+  /* We prefer the mmap() approach over the posix_memalign() or malloc()
+     based approaches, since the latter often waste an entire memory page
+     per call.  */
 #if HAVE_MMAP
 # ifdef HAVE_MAP_ANONYMOUS
   const int fd = -1;