[PATCH 1/9] getpagesize: improve doc

[Paul Eggert]

* doc/glibc-functions/getpagesize.texi:
Mention portability problems not fixed by Gnulib.
---
 ChangeLog                            |  6 ++++++
 doc/glibc-functions/getpagesize.texi | 13 +++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index f44aab79f6..9d06cc7eac 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-06-14  Paul Eggert  <eggert@cs.ucla.edu>
+
+       getpagesize: improve doc
+       * doc/glibc-functions/getpagesize.texi:
+       Mention portability problems not fixed by Gnulib.
+
 2024-06-14  Bruno Haible  <bruno@clisp.org>
 
        vasnprintf: Reject a width > INT_MAX.
diff --git a/doc/glibc-functions/getpagesize.texi 
b/doc/glibc-functions/getpagesize.texi
index 7b40f5e48d..77df489bce 100644
--- a/doc/glibc-functions/getpagesize.texi
+++ b/doc/glibc-functions/getpagesize.texi
@@ -33,5 +33,18 @@ mingw.
 @end itemize
 
 Portability problems not fixed by Gnulib:
+
 @itemize
+@item
+The function has never been in POSIX and was removed from the Single
+UNIX Specification in SUSv3 (2001).
+Although portable programs are supposed to use @code{sysconf (_SC_PAGESIZE)}
+instead, in practice @code{getpagesize} can be a little faster.
+
+@item
+On typical platforms this function's API limits page sizes to at most 1 GiB@,
+even though @code{sysconf (_SC_PAGESIZE)} does not have this limitation.
+However, this has not been a practical problem yet,
+and so many programs use @code{getpagesize} that it's unlikely that
+new platforms would introduce larger page sizes any time soon.
 @end itemize
-- 
2.45.2