getpagesize.2

getpagesize.2

[enh]

i'm not sure a lot of the text in getpagesize.2 is very helpful? for example:

       Portable applications should employ sysconf(_SC_PAGESIZE) instead
       of getpagesize():

           #include <unistd.h>
           long sz = sysconf(_SC_PAGESIZE);

       (Most systems allow the synonym _SC_PAGE_SIZE for _SC_PAGESIZE.)

is this a good recommendation _unless_ you've found yourself on a
system that doesn't have getpagesize()? on Android i'm advising
getpagesize() because it's (a) attribute const and (b) inherently
cheaper than sysconf(). (though obviously, "if it really matters,
stick it in a static".)

afaict the only motivation for the "portable applications" advice is
that HP-UX removed getpagesize() at some point? but given that HP-UX
has been kept "alive" in an artificial coma since 2007... does anyone
writing code in 2024 need to worry about that enough for this to be
good advice?

getpagesize() is available on Android, *BSD, iOS/macOS, glibc/musl,
and even mingw!

       Whether getpagesize() is present as a Linux system call depends
       on the architecture.  If it is, it returns the kernel symbol
       PAGE_SIZE, whose value depends on the architecture and machine
       model.  Generally, one uses binaries that are dependent on the
       architecture but not on the machine model, in order to have a
       single binary distribution per architecture.  This means that a
       user program should not find PAGE_SIZE at compile time from a
       header file, but use an actual system call, at least for those
       architectures (like sun4) where this dependency exists.

should this just say alpha, sparc32, and sparc64 instead of being
vague? (i suspect anyone who doesn't default to searching the kernel
source would turn to the man pages to answer the "which
architectures?" question :-) though i'm not sure why anyone who
doesn't read the kernel source would care whether getpagesize() should
really be in man2 or man3...)

       glibc 2.0 fails because its getpagesize() returns a statically
       derived value, and does not use a system call.  Things are OK in
       glibc 2.1.

1997 called, and wondered whether we're helping anyone by documenting
a bug that's been fixed longer than several folks on my team have been
alive? :-)

Re: getpagesize.2

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2821 bytes --]

Hi Elliott!

On Tue, Mar 26, 2024 at 03:27:27PM -0700, enh wrote:
> i'm not sure a lot of the text in getpagesize.2 is very helpful? for
> example:
> 
>        Portable applications should employ sysconf(_SC_PAGESIZE) instead
>        of getpagesize():
> 
>            #include <unistd.h>
>            long sz = sysconf(_SC_PAGESIZE);
> 
>        (Most systems allow the synonym _SC_PAGE_SIZE for _SC_PAGESIZE.)
> 
> is this a good recommendation _unless_ you've found yourself on a system
> that doesn't have getpagesize()? on Android i'm advising getpagesize()
> because it's (a) attribute const and (b) inherently cheaper than sysconf().
> (though obviously, "if it really matters, stick it in a static".)
> 
> afaict the only motivation for the "portable applications" advice is that
> HP-UX removed getpagesize() at some point? but given that HP-UX has been
> kept "alive" in an artificial coma since 2007... does anyone writing code
> in 2024 need to worry about that enough for this to be good advice?

I hope not.  It's dead, AFAIC.

> getpagesize() is available on Android, *BSD, iOS/macOS, glibc/musl, and
> even mingw!
> 
>        Whether getpagesize() is present as a Linux system call depends
>        on the architecture.  If it is, it returns the kernel symbol
>        PAGE_SIZE, whose value depends on the architecture and machine
>        model.  Generally, one uses binaries that are dependent on the
>        architecture but not on the machine model, in order to have a
>        single binary distribution per architecture.  This means that a
>        user program should not find PAGE_SIZE at compile time from a
>        header file, but use an actual system call, at least for those
>        architectures (like sun4) where this dependency exists.
> 
> should this just say alpha, sparc32, and sparc64 instead of being vague? (i

Yep, I'd appreciate that, after the current text (not replacing it).

> suspect anyone who doesn't default to searching the kernel source would
> turn to the man pages to answer the "which architectures?" question :-)
> though i'm not sure why anyone who doesn't read the kernel source would
> care whether getpagesize() should really be in man2 or man3...)
> 
>        glibc 2.0 fails because its getpagesize() returns a statically
>        derived value, and does not use a system call.  Things are OK in
>        glibc 2.1.
> 
> 1997 called, and wondered whether we're helping anyone by documenting a bug
> that's been fixed longer than several folks on my team have been alive? :-)

Agree.

Do you intend to send patches?  Otherwise, let me know, and I'll prepare
something.

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: getpagesize.2

[enh]

On Tue, Mar 26, 2024 at 4:20 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Elliott!
>
> On Tue, Mar 26, 2024 at 03:27:27PM -0700, enh wrote:
> > i'm not sure a lot of the text in getpagesize.2 is very helpful? for
> > example:
> >
> >        Portable applications should employ sysconf(_SC_PAGESIZE) instead
> >        of getpagesize():
> >
> >            #include <unistd.h>
> >            long sz = sysconf(_SC_PAGESIZE);
> >
> >        (Most systems allow the synonym _SC_PAGE_SIZE for _SC_PAGESIZE.)
> >
> > is this a good recommendation _unless_ you've found yourself on a system
> > that doesn't have getpagesize()? on Android i'm advising getpagesize()
> > because it's (a) attribute const and (b) inherently cheaper than sysconf().
> > (though obviously, "if it really matters, stick it in a static".)
> >
> > afaict the only motivation for the "portable applications" advice is that
> > HP-UX removed getpagesize() at some point? but given that HP-UX has been
> > kept "alive" in an artificial coma since 2007... does anyone writing code
> > in 2024 need to worry about that enough for this to be good advice?
>
> I hope not.  It's dead, AFAIC.
>
> > getpagesize() is available on Android, *BSD, iOS/macOS, glibc/musl, and
> > even mingw!
> >
> >        Whether getpagesize() is present as a Linux system call depends
> >        on the architecture.  If it is, it returns the kernel symbol
> >        PAGE_SIZE, whose value depends on the architecture and machine
> >        model.  Generally, one uses binaries that are dependent on the
> >        architecture but not on the machine model, in order to have a
> >        single binary distribution per architecture.  This means that a
> >        user program should not find PAGE_SIZE at compile time from a
> >        header file, but use an actual system call, at least for those
> >        architectures (like sun4) where this dependency exists.
> >
> > should this just say alpha, sparc32, and sparc64 instead of being vague? (i
>
> Yep, I'd appreciate that, after the current text (not replacing it).
>
> > suspect anyone who doesn't default to searching the kernel source would
> > turn to the man pages to answer the "which architectures?" question :-)
> > though i'm not sure why anyone who doesn't read the kernel source would
> > care whether getpagesize() should really be in man2 or man3...)
> >
> >        glibc 2.0 fails because its getpagesize() returns a statically
> >        derived value, and does not use a system call.  Things are OK in
> >        glibc 2.1.
> >
> > 1997 called, and wondered whether we're helping anyone by documenting a bug
> > that's been fixed longer than several folks on my team have been alive? :-)
>
> Agree.
>
> Do you intend to send patches?  Otherwise, let me know, and I'll prepare
> something.

i can do, but it also sounds like enough of a bikeshed that i imagine
you'd only want to rewrite it again anyway :-)

(i was actually surprised how many references to glibc 2.0 there are
in various man pages, and even more amused by references to "ancient
versions of glibc" being defined as "before glibc 2.0", as  if 1997
isn't ancient :-) )

> Have a lovely night!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.

Re: getpagesize.2

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1039 bytes --]

Hi Elliott,

On Wed, Mar 27, 2024 at 05:20:18PM -0700, enh wrote:
> > Do you intend to send patches?  Otherwise, let me know, and I'll prepare
> > something.
> 
> i can do, but it also sounds like enough of a bikeshed that i imagine
> you'd only want to rewrite it again anyway :-)

Actually, I tried to write something, and felt like you'll definitely do
better; I didn't like my text.  Please send a patch.  (I can do the
bikeshed when applying it, if you don't feel like entertaining it.)  :-}

> (i was actually surprised how many references to glibc 2.0 there are
> in various man pages, and even more amused by references to "ancient
> versions of glibc" being defined as "before glibc 2.0", as  if 1997
> isn't ancient :-) )

You can move anything like that to HISTORY sections in any page you see
it.  In some cases, it might make sense to remove it, but only if it was
a small bug.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: getpagesize.2

[enh]

[-- Attachment #1: Type: text/plain, Size: 1316 bytes --]

On Thu, Mar 28, 2024 at 2:11 AM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Elliott,
>
> On Wed, Mar 27, 2024 at 05:20:18PM -0700, enh wrote:
> > > Do you intend to send patches?  Otherwise, let me know, and I'll prepare
> > > something.
> >
> > i can do, but it also sounds like enough of a bikeshed that i imagine
> > you'd only want to rewrite it again anyway :-)
>
> Actually, I tried to write something, and felt like you'll definitely do
> better; I didn't like my text.  Please send a patch.  (I can do the
> bikeshed when applying it, if you don't feel like entertaining it.)  :-}

heh, i didn't even write mine out and had the same worry. oh well,
i've attached something so at least we have something concrete to talk
about!

> > (i was actually surprised how many references to glibc 2.0 there are
> > in various man pages, and even more amused by references to "ancient
> > versions of glibc" being defined as "before glibc 2.0", as  if 1997
> > isn't ancient :-) )
>
> You can move anything like that to HISTORY sections in any page you see
> it.  In some cases, it might make sense to remove it, but only if it was
> a small bug.
>
> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.

[-- Attachment #2: 0001-getpagesize.2-syscalls.2-modernization.patch --]
[-- Type: text/x-patch, Size: 3262 bytes --]

From e4e24a6a7ef66016edcd735f3cebc7f6583e716a Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Fri, 29 Mar 2024 17:10:26 -0700
Subject: [PATCH] getpagesize.2/syscalls.2: modernization.

Remove the HP-UX portability advice, since getpagesize() is a slightly
better option than sysconf() for Linux systems.

Explain why this function exists, and why this man page is in the wrong
section. (The previous text tried to do both at the same, which was
confusing.) Also explain how the vast majority of architectures that
don't have a syscall (but do support multiple page sizes) actually work.

Also de-emphasize the glibc 2.0 bug, since most people don't need to
worry about compatibility with versions of glibc from 1997.

Finally, change "not on x86" in syscalls.2 to say where there _is_ a
syscall.
---
 man2/getpagesize.2 | 47 ++++++++++------------------------------------
 man2/syscalls.2    |  4 +++-
 2 files changed, 13 insertions(+), 38 deletions(-)

diff --git a/man2/getpagesize.2 b/man2/getpagesize.2
index b82586f36..5d0006f04 100644
--- a/man2/getpagesize.2
+++ b/man2/getpagesize.2
@@ -44,46 +44,19 @@ This call first appeared in 4.2BSD.
 SVr4, 4.4BSD, SUSv2.
 In SUSv2 the
 .BR getpagesize ()
-call is labeled LEGACY, and in POSIX.1-2001
-it has been dropped;
-HP-UX does not have this call.
+call was labeled LEGACY, and it was removed in POSIX.1-2001.
 .SH NOTES
-Portable applications should employ
-.I sysconf(_SC_PAGESIZE)
-instead of
-.BR getpagesize ():
-.P
-.in +4n
-.EX
-#include <unistd.h>
-long sz = sysconf(_SC_PAGESIZE);
-.EE
-.in
-.P
-(Most systems allow the synonym
-.B _SC_PAGE_SIZE
-for
-.BR _SC_PAGESIZE .)
-.P
-Whether
-.BR getpagesize ()
-is present as a Linux system call depends on the architecture.
-If it is, it returns the kernel symbol
-.BR PAGE_SIZE ,
-whose value depends on the architecture and machine model.
-Generally, one uses binaries that are dependent on the architecture but not
-on the machine model, in order to have a single binary
-distribution per architecture.
-This means that a user program
-should not find
+A user program should not hard-code a page size,
+neither as a literal nor using the
 .B PAGE_SIZE
-at compile time from a header file,
-but use an actual system call, at least for those architectures
-(like sun4) where this dependency exists.
-Here glibc 2.0 fails because its
+macro, because some architectures support multiple page sizes.
+.P
+This manual page is in section 2 because Alpha, SPARC, and SPARC64
+all have a Linux system call
 .BR getpagesize ()
-returns a statically derived value, and does not use a system call.
-Things are OK in glibc 2.1.
+though other architectures do not, and use the ELF auxiliary vector
+instead. glibc 2.0 returned a constant even on architectures with mutliple
+page sizes.
 .SH SEE ALSO
 .BR mmap (2),
 .BR sysconf (3)
diff --git a/man2/syscalls.2 b/man2/syscalls.2
index 6c2313506..69f24ef29 100644
--- a/man2/syscalls.2
+++ b/man2/syscalls.2
@@ -324,7 +324,9 @@ T}
 \fBgetpeername\fP(2)	2.0	T{
 See notes on \fBsocketcall\fP(2)
 T}
-\fBgetpagesize\fP(2)	2.0	Not on x86
+\fBgetpagesize\fP(2)	2.0	T{
+Alpha, SPARC/SPARC64 only
+T}
 \fBgetpgid\fP(2)	1.0
 \fBgetpgrp\fP(2)	1.0
 \fBgetpid\fP(2)	1.0
-- 
2.44.0.478.gd926399ef9-goog

Re: getpagesize.2

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 6986 bytes --]

Hi Elliott,

On Fri, Mar 29, 2024 at 05:17:18PM -0700, enh wrote:
> On Thu, Mar 28, 2024 at 2:11 AM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > Hi Elliott,
> >
> > On Wed, Mar 27, 2024 at 05:20:18PM -0700, enh wrote:
> > > > Do you intend to send patches?  Otherwise, let me know, and I'll prepare
> > > > something.
> > >
> > > i can do, but it also sounds like enough of a bikeshed that i imagine
> > > you'd only want to rewrite it again anyway :-)
> >
> > Actually, I tried to write something, and felt like you'll definitely do
> > better; I didn't like my text.  Please send a patch.  (I can do the
> > bikeshed when applying it, if you don't feel like entertaining it.)  :-}
> 
> heh, i didn't even write mine out and had the same worry. oh well,
> i've attached something so at least we have something concrete to talk
> about!

:-)

> > > (i was actually surprised how many references to glibc 2.0 there are
> > > in various man pages, and even more amused by references to "ancient
> > > versions of glibc" being defined as "before glibc 2.0", as  if 1997
> > > isn't ancient :-) )
> >
> > You can move anything like that to HISTORY sections in any page you see
> > it.  In some cases, it might make sense to remove it, but only if it was
> > a small bug.
> >
> > Have a lovely day!
> > Alex
> >
> > --
> > <https://www.alejandro-colomar.es/>
> > Looking for a remote C programming job at the moment.

> From e4e24a6a7ef66016edcd735f3cebc7f6583e716a Mon Sep 17 00:00:00 2001
> From: Elliott Hughes <enh@google.com>
> Date: Fri, 29 Mar 2024 17:10:26 -0700
> Subject: [PATCH] getpagesize.2/syscalls.2: modernization.
> 
> Remove the HP-UX portability advice, since getpagesize() is a slightly
> better option than sysconf() for Linux systems.
> 
> Explain why this function exists, and why this man page is in the wrong
> section. (The previous text tried to do both at the same, which was
> confusing.) Also explain how the vast majority of architectures that
> don't have a syscall (but do support multiple page sizes) actually work.
> 
> Also de-emphasize the glibc 2.0 bug, since most people don't need to
> worry about compatibility with versions of glibc from 1997.
> 
> Finally, change "not on x86" in syscalls.2 to say where there _is_ a
> syscall.
> ---
>  man2/getpagesize.2 | 47 ++++++++++------------------------------------
>  man2/syscalls.2    |  4 +++-
>  2 files changed, 13 insertions(+), 38 deletions(-)
> 
> diff --git a/man2/getpagesize.2 b/man2/getpagesize.2
> index b82586f36..5d0006f04 100644
> --- a/man2/getpagesize.2
> +++ b/man2/getpagesize.2
> @@ -44,46 +44,19 @@ This call first appeared in 4.2BSD.
>  SVr4, 4.4BSD, SUSv2.
>  In SUSv2 the
>  .BR getpagesize ()
> -call is labeled LEGACY, and in POSIX.1-2001
> -it has been dropped;
> -HP-UX does not have this call.
> +call was labeled LEGACY, and it was removed in POSIX.1-2001.

LGTM

>  .SH NOTES
> -Portable applications should employ
> -.I sysconf(_SC_PAGESIZE)
> -instead of
> -.BR getpagesize ():
> -.P
> -.in +4n
> -.EX
> -#include <unistd.h>
> -long sz = sysconf(_SC_PAGESIZE);
> -.EE
> -.in
> -.P
> -(Most systems allow the synonym
> -.B _SC_PAGE_SIZE
> -for
> -.BR _SC_PAGESIZE .)
> -.P
> -Whether
> -.BR getpagesize ()
> -is present as a Linux system call depends on the architecture.
> -If it is, it returns the kernel symbol
> -.BR PAGE_SIZE ,
> -whose value depends on the architecture and machine model.
> -Generally, one uses binaries that are dependent on the architecture but not
> -on the machine model, in order to have a single binary
> -distribution per architecture.
> -This means that a user program
> -should not find
> +A user program should not hard-code a page size,
> +neither as a literal nor using the
>  .B PAGE_SIZE
> -at compile time from a header file,
> -but use an actual system call, at least for those architectures
> -(like sun4) where this dependency exists.
> -Here glibc 2.0 fails because its
> +macro, because some architectures support multiple page sizes.
> +.P
> +This manual page is in section 2 because Alpha, SPARC, and SPARC64
> +all have a Linux system call
>  .BR getpagesize ()
> -returns a statically derived value, and does not use a system call.
> -Things are OK in glibc 2.1.
> +though other architectures do not, and use the ELF auxiliary vector

Remember to use semantic newlines.  :)

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p';
   Use semantic newlines
     In  the  source of a manual page, new sentences should be started
     on new lines, long sentences should be split into lines at clause
     breaks (commas, semicolons, colons, and so on), and long  clauses
     should be split at phrase boundaries.  This convention, sometimes
     known  as  "semantic newlines", makes it easier to see the effect
     of patches, which often operate at the level of  individual  sen‐
     tences, clauses, or phrases.

> +instead. glibc 2.0 returned a constant even on architectures with mutliple
> +page sizes.

I would maybe move the glibc 2.0 comment to HISTORY.  Someone interested
in these NOTES probably doesn't care about that detail, unless they care
about HISTORY.  The fact that HISTORY goes before NOTES is a bit bad for
this, but I was thinking that the new text fits well a VERSIONS section,
so we could move it before HISTORY in a new VERSIONS section.  Here's
what I'm thinking of:

VERSIONS
     A  user  program  should  not hard‐code a page size, neither as a
     literal nor using the PAGE_SIZE macro, because some architectures
     support multiple page sizes.

     This manual page is  in  section  2  because  Alpha,  SPARC,  and
     SPARC64  all  have a Linux system call getpagesize() though other
     architectures do not, and use the ELF auxiliary  vector  instead.

HISTORY
     This  call  first  appeared  in 4.2BSD.  SVr4, 4.4BSD, SUSv2.  In
     SUSv2 the getpagesize() call was labeled LEGACY, and it  was  re‐
     moved in POSIX.1‐2001.

     glibc 2.0 returned a constant even on architectures with mutliple
     page sizes.

This order reinforces the sense that this function is preferred, being
documented first, and that POSIX removed it is unimportant to us, and
lower in the page.

>  .SH SEE ALSO
>  .BR mmap (2),
>  .BR sysconf (3)
> diff --git a/man2/syscalls.2 b/man2/syscalls.2
> index 6c2313506..69f24ef29 100644
> --- a/man2/syscalls.2
> +++ b/man2/syscalls.2
> @@ -324,7 +324,9 @@ T}
>  \fBgetpeername\fP(2)	2.0	T{
>  See notes on \fBsocketcall\fP(2)
>  T}
> -\fBgetpagesize\fP(2)	2.0	Not on x86
> +\fBgetpagesize\fP(2)	2.0	T{
> +Alpha, SPARC/SPARC64 only
> +T}

LGTM

Have a lovely night!
Alex

>  \fBgetpgid\fP(2)	1.0
>  \fBgetpgrp\fP(2)	1.0
>  \fBgetpid\fP(2)	1.0
> -- 
> 2.44.0.478.gd926399ef9-goog
> 


-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: getpagesize.2

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1376 bytes --]

Hi Elliott,

On Sun, Mar 31, 2024 at 12:24:12AM +0100, Alejandro Colomar wrote:
> > From e4e24a6a7ef66016edcd735f3cebc7f6583e716a Mon Sep 17 00:00:00 2001
> > From: Elliott Hughes <enh@google.com>
> > Date: Fri, 29 Mar 2024 17:10:26 -0700
> > Subject: [PATCH] getpagesize.2/syscalls.2: modernization.
> > 
> > Remove the HP-UX portability advice, since getpagesize() is a slightly
> > better option than sysconf() for Linux systems.
> > 
> > Explain why this function exists, and why this man page is in the wrong
> > section. (The previous text tried to do both at the same, which was
> > confusing.) Also explain how the vast majority of architectures that
> > don't have a syscall (but do support multiple page sizes) actually work.
> > 
> > Also de-emphasize the glibc 2.0 bug, since most people don't need to
> > worry about compatibility with versions of glibc from 1997.
> > 
> > Finally, change "not on x86" in syscalls.2 to say where there _is_ a
> > syscall.

I've applied it, with my suggestions on top, and pushed it here:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=c1e10426dc22ca976ba1107f7ca95a373bb22f83>

It'll stay there for a few days, and then to master.  If you want to
send a Signed-off-by, I'll add it.

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]