manual: add syscall list appendix

manual: add syscall list appendix

[DJ Delorie]

[the choice, wording, and formatting is - I admit - rough, but this
was the best I could come up with without feedback ;]

diff --git a/manual/Makefile b/manual/Makefile
index b5fda4a7ae..1e2800f409 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
 
 # Generated files directly included from libc.texinfo.
 libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
-		      libm-err.texi version.texi pkgvers.texi
+		      libm-err.texi version.texi pkgvers.texi \
+		      syscalls.texi
 
 # Add path to build dir for generated files
 texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
@@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c
 	    $< | expand > $@.new
 	mv -f $@.new $@
 
+# Generate a list of wrapped syscalls
+$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
+$(objpfx)stamp-syscalls: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscalls-tmp
+	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
+	touch $@
+
 $(objpfx)%.info: %.texinfo
 	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
 
diff --git a/manual/platform.texi b/manual/platform.texi
index 478b6fdcdf..92541208a5 100644
--- a/manual/platform.texi
+++ b/manual/platform.texi
@@ -2,12 +2,13 @@
 @c %MENU% Describe all platform-specific facilities provided
 @appendix Platform-specific facilities
 
-@Theglibc{} can provide machine-specific functionality.
+@Theglibc{} can provide machine-specific and kernel-specific functionality.
 
 @menu
 * PowerPC::           Facilities Specific to the PowerPC Architecture
 * RISC-V::            Facilities Specific to the RISC-V Architecture
 * X86::               Facilities Specific to the X86 Architecture
+* Syscalls::	      System Call Interface for Supported Kernels
 @end menu
 
 @node PowerPC
@@ -772,3 +773,21 @@ avx_active (void)
   return CPU_FEATURE_ACTIVE (AVX);
 @}
 @end smallexample
+
+@node Syscalls
+@appendixsec Kernel System Calls
+
+@Theglibc{} provides, in addition to its own API, an interface to the
+kernel for which it's configured.  This interface is a purely
+mechanical translation from the kernel's ABI to the C ABI.  Where such
+functions are not otherwise documented in this manual, please refer to
+the relvent kernel's documentation (for the Linux kernel, this is the
+@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project})
+for information on calling these functions.
+
+The comprehensive list of kernel system calls that may be mapped to C
+functions follows.  Note that this list includes calls for all kernels
+@theglibc{} supports, whereas in the real world only those calls
+supported by the configured and/or running kernel will be available.
+
+@include{syscalls.texi}

Re: manual: add syscall list appendix

[Florian Weimer]

* DJ Delorie:

> [the choice, wording, and formatting is - I admit - rough, but this
> was the best I could come up with without feedback ;]
>
> diff --git a/manual/Makefile b/manual/Makefile
> index b5fda4a7ae..1e2800f409 100644
> --- a/manual/Makefile
> +++ b/manual/Makefile
> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
>  
>  # Generated files directly included from libc.texinfo.
>  libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
> -		      libm-err.texi version.texi pkgvers.texi
> +		      libm-err.texi version.texi pkgvers.texi \
> +		      syscalls.texi
>  
>  # Add path to build dir for generated files
>  texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
> @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c
>  	    $< | expand > $@.new
>  	mv -f $@.new $@
>  
> +# Generate a list of wrapped syscalls
> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \
> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscalls-tmp
> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> +	touch $@

I ran the list through “sysdeps/unix/sysv/linux/glibcsyscalls.py
query-syscall”, and the following system calls do not actually exist
on any architecture:

  adjtime chflags fchflags getdomain getdtsz gethostid killpg klogctl
  lseek64 posix_fadvise64 revoke sched_getp sched_gets sched_primax
  sched_primin sched_setp sched_sets setdomain setegid seteuid sethostid
  setlogin sigpause sigstack syscall_clock_gettime

Maybe we should clean this up and remove those from the syscalls.list
files?

In the other direction, the list contains setgid setuid, setregid,
setreuid, which are not syscall wrappers by most definitions of the term
because they involve the setXid broadcast.

> +@Theglibc{} provides, in addition to its own API, an interface to the
> +kernel for which it's configured.  This interface is a purely
> +mechanical translation from the kernel's ABI to the C ABI.  Where such
> +functions are not otherwise documented in this manual, please refer to
> +the relvent kernel's documentation (for the Linux kernel, this is the
> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project})
> +for information on calling these functions.

Are the manual pages really official kernel documentation?  They are
out-of-tree, with separate maintainers, and a different development
process.

Thanks,
Florian

Re: manual: add syscall list appendix

[Carlos O'Donell]

On 5/16/24 1:02 AM, Florian Weimer wrote:
> * DJ Delorie:
> 
>> [the choice, wording, and formatting is - I admit - rough, but this
>> was the best I could come up with without feedback ;]

Adding Alejandro to TO: for any input.

This needs a configure argument to specify which version of the Linux man-pages project
release is the version we've looked at to make sure we match the behaviour for the
specified syscalls.

I think we should specifically reference e.g. Linux man-pages X.Y.

>> diff --git a/manual/Makefile b/manual/Makefile
>> index b5fda4a7ae..1e2800f409 100644
>> --- a/manual/Makefile
>> +++ b/manual/Makefile
>> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
>>  
>>  # Generated files directly included from libc.texinfo.
>>  libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
>> -		      libm-err.texi version.texi pkgvers.texi
>> +		      libm-err.texi version.texi pkgvers.texi \
>> +		      syscalls.texi
>>  
>>  # Add path to build dir for generated files
>>  texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
>> @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c
>>  	    $< | expand > $@.new
>>  	mv -f $@.new $@
>>  
>> +# Generate a list of wrapped syscalls
>> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
>> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
>> +	cat `find ../sysdeps -name syscalls.list -print` \
>> +	| sed -e '/^[^_a-zA-Z]/d' \
>> +	      -e 's/[ \t].*//' \
>> +	      -e 's/^/@code{/; s/$$/}/' \
>> +	| sort -u \
>> +	> $(objpfx)syscalls-tmp
>> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
>> +	touch $@

What about syscalls that have cancellation?

We should really split them out and document that we wrap them in special cancellation
code (which will change a bit as I need to review Adhemerval's changes for that).

> I ran the list through “sysdeps/unix/sysv/linux/glibcsyscalls.py
> query-syscall”, and the following system calls do not actually exist
> on any architecture:
> 
>   adjtime chflags fchflags getdomain getdtsz gethostid killpg klogctl
>   lseek64 posix_fadvise64 revoke sched_getp sched_gets sched_primax
>   sched_primin sched_setp sched_sets setdomain setegid seteuid sethostid
>   setlogin sigpause sigstack syscall_clock_gettime
> 
> Maybe we should clean this up and remove those from the syscalls.list
> files?
> 
> In the other direction, the list contains setgid setuid, setregid,
> setreuid, which are not syscall wrappers by most definitions of the term
> because they involve the setXid broadcast.
> 
>> +@Theglibc{} provides, in addition to its own API, an interface to the
>> +kernel for which it's configured.  This interface is a purely
>> +mechanical translation from the kernel's ABI to the C ABI.  Where such
>> +functions are not otherwise documented in this manual, please refer to
>> +the relvent kernel's documentation (for the Linux kernel, this is the
>> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project})
>> +for information on calling these functions.
> 
> Are the manual pages really official kernel documentation?  They are
> out-of-tree, with separate maintainers, and a different development
> process.

I think we should be honest in this description.

Suggest:
~~~
@Theglibc{} provides, in addition to its own API, an interface to the
kernel for which it's configured.  This interface is mostly a purely
mechanical translation from the kernel's ABI to the C ABI. For the set
of syscalls where we do not guarantee POSIX Thread cancellation the
wrappers only organize the incoming arguments from the C calling convention
to the calling convention of the target kernel. For the set of syscalls
where we provided POSIX Thread cancellation the wrappers set some internal
state in the library to support cancellation, but this does not impact
the behaviour of the syscall provided by the kernel.

@Theglibc{} includes by reference the Linux man-pages X.Y documentation 
to document the listed syscalls for the Linux kernel. For reference purposes only
the latest @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
documentation can be accessed from the @uref{https://www.kernel.org,Linux kernel}
website. Where the syscall has more specific documentation in this manual that
more specific documentation is considered authoritative.
~~~

The intent is to say that if we didn't document anything in the glibc manual
that users should feel free to go read the Linux man-pages documentaiton for
that syscall.

Thoughts?

-- 
Cheers,
Carlos.

Re: manual: add syscall list appendix

[Florian Weimer]

* Carlos O'Donell:

>>> +# Generate a list of wrapped syscalls
>>> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
>>> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
>>> +	cat `find ../sysdeps -name syscalls.list -print` \
>>> +	| sed -e '/^[^_a-zA-Z]/d' \
>>> +	      -e 's/[ \t].*//' \
>>> +	      -e 's/^/@code{/; s/$$/}/' \
>>> +	| sort -u \
>>> +	> $(objpfx)syscalls-tmp
>>> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
>>> +	touch $@
>
> What about syscalls that have cancellation?

They have argument lists that start with C (usually Ci:).

Thanks,
Florian

Re: manual: add syscall list appendix

[Alejandro Colomar]

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

Hey Carlos!

On Thu, May 16, 2024 at 07:44:42AM GMT, Carlos O'Donell wrote:
> On 5/16/24 1:02 AM, Florian Weimer wrote:
> > * DJ Delorie:
> > 
> >> [the choice, wording, and formatting is - I admit - rough, but this
> >> was the best I could come up with without feedback ;]
> 
> Adding Alejandro to TO: for any input.

I'm not using the @gmail.com account anymore.  I still have it
forwarding to my current mailbox, to reveive mail sent to that address,
but please don't send anything there, since some day I'll remove the
account.  Please use <alx@kernel.org> which now forwards to my new
mailbox at <foss@alejandro-colomar.es>.

> This needs a configure argument to specify which version of the Linux man-pages project
> release is the version we've looked at to make sure we match the behaviour for the
> specified syscalls.
> 
> I think we should specifically reference e.g. Linux man-pages X.Y.

I'll check later.  Can you tell me a little bit more about what you're
doing and what you want feedback about?

Have a lovely day!
Alex

> 
> >> diff --git a/manual/Makefile b/manual/Makefile
> >> index b5fda4a7ae..1e2800f409 100644
> >> --- a/manual/Makefile
> >> +++ b/manual/Makefile
> >> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
> >>  
> >>  # Generated files directly included from libc.texinfo.
> >>  libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
> >> -		      libm-err.texi version.texi pkgvers.texi
> >> +		      libm-err.texi version.texi pkgvers.texi \
> >> +		      syscalls.texi
> >>  
> >>  # Add path to build dir for generated files
> >>  texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
> >> @@ -138,6 +139,18 @@ $(objpfx)%.c.texi: examples/%.c
> >>  	    $< | expand > $@.new
> >>  	mv -f $@.new $@
> >>  
> >> +# Generate a list of wrapped syscalls
> >> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> >> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> >> +	cat `find ../sysdeps -name syscalls.list -print` \
> >> +	| sed -e '/^[^_a-zA-Z]/d' \
> >> +	      -e 's/[ \t].*//' \
> >> +	      -e 's/^/@code{/; s/$$/}/' \
> >> +	| sort -u \
> >> +	> $(objpfx)syscalls-tmp
> >> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> >> +	touch $@
> 
> What about syscalls that have cancellation?
> 
> We should really split them out and document that we wrap them in special cancellation
> code (which will change a bit as I need to review Adhemerval's changes for that).
> 
> > I ran the list through “sysdeps/unix/sysv/linux/glibcsyscalls.py
> > query-syscall”, and the following system calls do not actually exist
> > on any architecture:
> > 
> >   adjtime chflags fchflags getdomain getdtsz gethostid killpg klogctl
> >   lseek64 posix_fadvise64 revoke sched_getp sched_gets sched_primax
> >   sched_primin sched_setp sched_sets setdomain setegid seteuid sethostid
> >   setlogin sigpause sigstack syscall_clock_gettime
> > 
> > Maybe we should clean this up and remove those from the syscalls.list
> > files?
> > 
> > In the other direction, the list contains setgid setuid, setregid,
> > setreuid, which are not syscall wrappers by most definitions of the term
> > because they involve the setXid broadcast.
> > 
> >> +@Theglibc{} provides, in addition to its own API, an interface to the
> >> +kernel for which it's configured.  This interface is a purely
> >> +mechanical translation from the kernel's ABI to the C ABI.  Where such
> >> +functions are not otherwise documented in this manual, please refer to
> >> +the relvent kernel's documentation (for the Linux kernel, this is the
> >> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project})
> >> +for information on calling these functions.
> > 
> > Are the manual pages really official kernel documentation?  They are
> > out-of-tree, with separate maintainers, and a different development
> > process.
> 
> I think we should be honest in this description.
> 
> Suggest:
> ~~~
> @Theglibc{} provides, in addition to its own API, an interface to the
> kernel for which it's configured.  This interface is mostly a purely
> mechanical translation from the kernel's ABI to the C ABI. For the set
> of syscalls where we do not guarantee POSIX Thread cancellation the
> wrappers only organize the incoming arguments from the C calling convention
> to the calling convention of the target kernel. For the set of syscalls
> where we provided POSIX Thread cancellation the wrappers set some internal
> state in the library to support cancellation, but this does not impact
> the behaviour of the syscall provided by the kernel.
> 
> @Theglibc{} includes by reference the Linux man-pages X.Y documentation 
> to document the listed syscalls for the Linux kernel. For reference purposes only
> the latest @uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
> documentation can be accessed from the @uref{https://www.kernel.org,Linux kernel}
> website. Where the syscall has more specific documentation in this manual that
> more specific documentation is considered authoritative.
> ~~~
> 
> The intent is to say that if we didn't document anything in the glibc manual
> that users should feel free to go read the Linux man-pages documentaiton for
> that syscall.
> 
> Thoughts?
> 
> -- 
> Cheers,
> Carlos.
> 

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

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

Re: manual: add syscall list appendix

[Carlos O'Donell]

On 5/16/24 9:37 AM, Alejandro Colomar wrote:
> Hey Carlos!
> 
> On Thu, May 16, 2024 at 07:44:42AM GMT, Carlos O'Donell wrote:
>> On 5/16/24 1:02 AM, Florian Weimer wrote:
>>> * DJ Delorie:
>>>
>>>> [the choice, wording, and formatting is - I admit - rough, but this
>>>> was the best I could come up with without feedback ;]
>>
>> Adding Alejandro to TO: for any input.
> 
> I'm not using the @gmail.com account anymore.  I still have it
> forwarding to my current mailbox, to reveive mail sent to that address,
> but please don't send anything there, since some day I'll remove the
> account.  Please use <alx@kernel.org> which now forwards to my new
> mailbox at <foss@alejandro-colomar.es>.

Done. Updated address book.

>> This needs a configure argument to specify which version of the Linux man-pages project
>> release is the version we've looked at to make sure we match the behaviour for the
>> specified syscalls.
>>
>> I think we should specifically reference e.g. Linux man-pages X.Y.
> 
> I'll check later.  Can you tell me a little bit more about what you're
> doing and what you want feedback about?

Where glibc provides only syscall wrappers I want to include by reference the Linux
man-pages descriptions, at a specific version, for the behaviour of those APIs.

This has two positive benefits:

- Focuses all of our efforts on keeping linux man-pages accurate for the syscall
  wrappers.

- Provides glibc documentation for the APIs by way of a normative reference.

  - This may be required from a process perspective if anyone is using glibc
    in an implementation that attempts to attain standards conformance for
    the APIs in question e.g. ISO 9001, IEC 61508, IEC 61511-1, or ISO 26262.

Right now we lack documentation for epoll for example in glibc, and to recreate
that would be a lot of work, and I think a collaboration between the glibc manual
and the Linux man-pages project would be a better solution.

-- 
Cheers,
Carlos.

Re: manual: add syscall list appendix

[Alejandro Colomar]

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

Hi Carlos,

On Thu, May 16, 2024 at 10:52:22AM GMT, Carlos O'Donell wrote:
> >> This needs a configure argument to specify which version of the Linux man-pages project
> >> release is the version we've looked at to make sure we match the behaviour for the
> >> specified syscalls.
> >>
> >> I think we should specifically reference e.g. Linux man-pages X.Y.
> > 
> > I'll check later.  Can you tell me a little bit more about what you're
> > doing and what you want feedback about?
> 
> Where glibc provides only syscall wrappers I want to include by reference the Linux
> man-pages descriptions, at a specific version, for the behaviour of those APIs.

LGTM.  For such change:

Acked-by: Alejandro Colomar <alx@kernel.org>

> This has two positive benefits:
> 
> - Focuses all of our efforts on keeping linux man-pages accurate for the syscall
>   wrappers.
> 
> - Provides glibc documentation for the APIs by way of a normative reference.
> 
>   - This may be required from a process perspective if anyone is using glibc
>     in an implementation that attempts to attain standards conformance for
>     the APIs in question e.g. ISO 9001, IEC 61508, IEC 61511-1, or ISO 26262.
> 
> Right now we lack documentation for epoll for example in glibc, and to recreate
> that would be a lot of work, and I think a collaboration between the glibc manual
> and the Linux man-pages project would be a better solution.

Sure!  Whatever you need from me, please let me know.

I'm also trying to write in the HISTORY section of manual pages any
important changes that have affected functions, so if you want to add
details to any page in those sections to make more clear the glibc
versions that added support, or some other changes, they're very
welcome.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
A client is hiring kernel driver, mm, and/or crypto developers;
contact me if interested.

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

Re: manual: add syscall list appendix

[DJ Delorie]

Florian Weimer <fweimer@redhat.com> writes:
> Maybe we should clean this up and remove those from the syscalls.list
> files?

If this patch triggers a cleanup of syscall information, I'm all for
that ;-)

I debated documenting the *found* syscalls vs the *listed* syscalls but
I didn't want the manual to be specific to the configured target.  Hurd
doesn't have wrapped syscalls (I think ;) and BSD *is* listed with
syscalls, so those were included, along with all the Linux variants.

>> +@Theglibc{} provides, in addition to its own API, an interface to the
>> +kernel for which it's configured.  This interface is a purely
>> +mechanical translation from the kernel's ABI to the C ABI.  Where such
>> +functions are not otherwise documented in this manual, please refer to
>> +the relvent kernel's documentation (for the Linux kernel, this is the
>> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project})
>> +for information on calling these functions.
>
> Are the manual pages really official kernel documentation?  They are
> out-of-tree, with separate maintainers, and a different development
> process.

They're way more official than the in-tree kernel documentation... oh
wait, the kernel has NO DOCUMENTATION ON ITS API.

The man pages are more likely to be correct and up to date than the
glibc manual.  The alternative is to duplicate all that work into the
glibc manual.

Besides, I didn't say "official" I said "relevent" ;-)

Re: manual: add syscall list appendix

[DJ Delorie]

"Carlos O'Donell" <carlos@redhat.com> writes:
> This needs a configure argument to specify which version of the Linux man-pages project
> release is the version we've looked at to make sure we match the behaviour for the
> specified syscalls.
>
> I think we should specifically reference e.g. Linux man-pages X.Y.

Can we make that optional?  I.e. if *no* configure option is specified,
the wording is version-agnostic?  Development in git likely doesn't care
which version of man-pages is current, and it would be continuously
changing anyway.  We would only need to lock-step in released versions
of glibc, and then, we'd need to hard-code it somewhere as a default.

> What about syscalls that have cancellation?
>
> We should really split them out and document that we wrap them in special cancellation
> code (which will change a bit as I need to review Adhemerval's changes for that).

I'll see what I can do ;-)

> The intent is to say that if we didn't document anything in the glibc manual
> that users should feel free to go read the Linux man-pages documentaiton for
> that syscall.
>
> Thoughts?

It's long for an appendix.  Do we have a chapter on cancellation?  Do we
want to be that Linux-centric?

Re: manual: add syscall list appendix

[Joe Simmons-Talbott]

On Thu, May 16, 2024 at 1:38 PM DJ Delorie <dj@redhat.com> wrote:
>
> Florian Weimer <fweimer@redhat.com> writes:
> > Maybe we should clean this up and remove those from the syscalls.list
> > files?
>
> If this patch triggers a cleanup of syscall information, I'm all for
> that ;-)
>
> I debated documenting the *found* syscalls vs the *listed* syscalls but
> I didn't want the manual to be specific to the configured target.  Hurd
> doesn't have wrapped syscalls (I think ;) and BSD *is* listed with
> syscalls, so those were included, along with all the Linux variants.
>
> >> +@Theglibc{} provides, in addition to its own API, an interface to the
> >> +kernel for which it's configured.  This interface is a purely
> >> +mechanical translation from the kernel's ABI to the C ABI.  Where such
> >> +functions are not otherwise documented in this manual, please refer to
> >> +the relvent kernel's documentation (for the Linux kernel, this is the

relevant

> >> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project})
> >> +for information on calling these functions.
> >
> > Are the manual pages really official kernel documentation?  They are
> > out-of-tree, with separate maintainers, and a different development
> > process.
>
> They're way more official than the in-tree kernel documentation... oh
> wait, the kernel has NO DOCUMENTATION ON ITS API.
>
> The man pages are more likely to be correct and up to date than the
> glibc manual.  The alternative is to duplicate all that work into the
> glibc manual.
>
> Besides, I didn't say "official" I said "relevent" ;-)
>


-- 
Joe Simmons-Talbott

Re: manual: add syscall list appendix

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> I'll check later.  Can you tell me a little bit more about what you're
> doing and what you want feedback about?

Along with what Carlos said, keep in mind that the glibc manual is GFDL
so cutting and pasting from the man pages project is a no-no.
Reproducing all your hard would would be just as hard for us as it was
for you ;-)

Re: manual: add syscall list appendix

[Alejandro Colomar]

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

On Thu, May 16, 2024 at 01:55:08PM GMT, DJ Delorie wrote:
> > The intent is to say that if we didn't document anything in the glibc manual
> > that users should feel free to go read the Linux man-pages documentaiton for
> > that syscall.
> >
> > Thoughts?
> 
> It's long for an appendix.  Do we have a chapter on cancellation?  Do we
> want to be that Linux-centric?

Hi DJ,

In the Linux man-pages project, we document primarily the Linux and
glibc interfaces, but we also document the behavior of other systems
such as the BSDs or musl when it differs, normally in the VERSIONS
section.

I would welcome patches for documenting for example GNU Hurd details,
or any other (FOSS) systems that provide the same interfaces.

And already during Michael Kerrisk's maintainership, he had a strong
interest for documenting portability to other Unix systems.

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
A client is hiring kernel driver, mm, and/or crypto developers;
contact me if interested.

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

Re: manual: add syscall list appendix

[Carlos O'Donell]

On 5/16/24 1:55 PM, DJ Delorie wrote:
> "Carlos O'Donell" <carlos@redhat.com> writes:
>> This needs a configure argument to specify which version of the Linux man-pages project
>> release is the version we've looked at to make sure we match the behaviour for the
>> specified syscalls.
>>
>> I think we should specifically reference e.g. Linux man-pages X.Y.
> 
> Can we make that optional?  I.e. if *no* configure option is specified,
> the wording is version-agnostic?  Development in git likely doesn't care
> which version of man-pages is current, and it would be continuously
> changing anyway.  We would only need to lock-step in released versions
> of glibc, and then, we'd need to hard-code it somewhere as a default.

$0.02. No. This is similar to the Linux kernel version checks. We should have a minimum
and bump them up as we audit and review.

>> What about syscalls that have cancellation?
>>
>> We should really split them out and document that we wrap them in special cancellation
>> code (which will change a bit as I need to review Adhemerval's changes for that).
> 
> I'll see what I can do ;-)
> 
>> The intent is to say that if we didn't document anything in the glibc manual
>> that users should feel free to go read the Linux man-pages documentaiton for
>> that syscall.
>>
>> Thoughts?
> 
> It's long for an appendix.  Do we have a chapter on cancellation?  Do we
> want to be that Linux-centric?

May you please expand on what you think is long for an appendix?

There are 117 undocumented POSIX Thread APIs in glibc that we *really* need to document,
but I am not asking you to document those. We do not talk about cancellation in the manual,
but we should. I don't think we need to do that for this patch, but we should correctly
note which have cancellation support and leave it at that.

We can be as Linux-centric as we want... so long as the manual is accurate and describes
these as Linux-specific things. We do this often in the manual.

-- 
Cheers,
Carlos.

Re: manual: add syscall list appendix

[DJ Delorie]

"Carlos O'Donell" <carlos@redhat.com> writes:
> $0.02. No. This is similar to the Linux kernel version checks. We should have a minimum
> and bump them up as we audit and review.

Then it needs to be recorded somewhere other than the configure line,
because 99.9% of all ./configure will not include it.

>> It's long for an appendix.  Do we have a chapter on cancellation?  Do we
>> want to be that Linux-centric?
>
> May you please expand on what you think is long for an appendix?

We're up to two long paragraphs about how glibc does syscalls, in
general, including cancellation.  Do we mention cancellation anywhere
else in the manual?  Do we have a chapter on how we wrap kernel-level
syscalls?  I'm thinking, is there enough information here to either move
the whole thing into a real chapter, or separate the big paragraphs from
the generated list?

Re: manual: add syscall list appendix

[Carlos O'Donell]

On 5/17/24 11:31 AM, DJ Delorie wrote:
> "Carlos O'Donell" <carlos@redhat.com> writes:
>> $0.02. No. This is similar to the Linux kernel version checks. We should have a minimum
>> and bump them up as we audit and review.
> 
> Then it needs to be recorded somewhere other than the configure line,
> because 99.9% of all ./configure will not include it.

Agreed.

Just like we store 'arch_minimum_kernel' today.

>>> It's long for an appendix.  Do we have a chapter on cancellation?  Do we
>>> want to be that Linux-centric?
>>
>> May you please expand on what you think is long for an appendix?
> 
> We're up to two long paragraphs about how glibc does syscalls, in
> general, including cancellation.  Do we mention cancellation anywhere
> else in the manual?  Do we have a chapter on how we wrap kernel-level
> syscalls?  I'm thinking, is there enough information here to either move
> the whole thing into a real chapter, or separate the big paragraphs from
> the generated list?

We mention POSIX Thread cancellation in intro.texi as part of our
discussions about asynchronous-cancellation safety (which only a few
functions are), since we explain that it applies. We don't really
describe what it is, expecting developers to be familiar with the
concept from POSIX itself e.g.
https://pubs.opengroup.org/onlinepubs/009695399/functions/xsh_chap02_09.html
"2.9.5 Thread Cancellation"

AFAIK we have no chapter discussing how we wrap the kernel-level syscalls.

I agree there is enough information here to create a new chapter.

I suggest a real chapter somewhere in the manual to discuss the
syscall wrappers and syscall wrappers that support deferred POSIX
Thread cancellation. Along with listing the generated list of wrappers.

-- 
Cheers,
Carlos.

[patch v2] manual: add syscall list

[DJ Delorie]

[Found a spot where we documneted syscall() and there was a natural
place to insert these docs there.  Defaulted to man-pages 6.7 (current
rawhide) as I have no reason to pick any other version.  DJ]

Default version of man-pages is in configure.ac but can be overridden
by --with-man-pages=X.Y

diff --git a/config.make.in b/config.make.in
index 55e8b7563b..36096881b7 100644
--- a/config.make.in
+++ b/config.make.in
@@ -91,6 +91,7 @@ use-nscd = @use_nscd@
 build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
 build-pt-chown = @build_pt_chown@
 pthread-in-libc = @pthread_in_libc@
+man-pages-version = @man_pages_version@
 
 # Build tools.
 CC = @CC@
diff --git a/configure b/configure
index 432e40a592..87b99f0c86 100755
--- a/configure
+++ b/configure
@@ -706,6 +706,7 @@ force_install
 bindnow
 hardcoded_path_in_tests
 enable_timezone_tools
+man_pages_version
 rtld_early_cflags
 extra_nonshared_cflags
 sysheaders
@@ -787,6 +788,7 @@ with_headers
 with_nonshared_cflags
 with_rtld_early_cflags
 with_timeoutfactor
+with_man_pages
 enable_sanity_checks
 enable_shared
 enable_profile
@@ -1509,6 +1511,8 @@ Optional Packages:
                           build early initialization with additional CFLAGS
   --with-timeoutfactor=NUM
                           specify an integer to scale the timeout
+  --with-man-pages=VERSION
+                          tie manual to a specific man-pages version
   --with-cpu=CPU          select code for CPU variant
 
 Some influential environment variables:
@@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
 then :
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++11 features" >&5
 printf %s "checking for $CXX option to enable C++11 features... " >&6; }
-if test ${ac_cv_prog_cxx_cxx11+y}
+if test ${ac_cv_prog_cxx_11+y}
 then :
   printf %s "(cached) " >&6
 else $as_nop
-  ac_cv_prog_cxx_cxx11=no
+  ac_cv_prog_cxx_11=no
 ac_save_CXX=$CXX
 cat confdefs.h - <<_ACEOF >conftest.$ac_ext
 /* end confdefs.h.  */
@@ -4137,11 +4141,11 @@ if test x$ac_prog_cxx_stdcxx = xno
 then :
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++98 features" >&5
 printf %s "checking for $CXX option to enable C++98 features... " >&6; }
-if test ${ac_cv_prog_cxx_cxx98+y}
+if test ${ac_cv_prog_cxx_98+y}
 then :
   printf %s "(cached) " >&6
 else $as_nop
-  ac_cv_prog_cxx_cxx98=no
+  ac_cv_prog_cxx_98=no
 ac_save_CXX=$CXX
 cat confdefs.h - <<_ACEOF >conftest.$ac_ext
 /* end confdefs.h.  */
@@ -4374,6 +4378,17 @@ fi
 printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
 
 
+man_pages_version=6.7
+
+
+# Check whether --with-man-pages was given.
+if test ${with_man_pages+y}
+then :
+  withval=$with_man_pages; man_pages_version=$withval
+fi
+
+
+
 # Check whether --enable-sanity-checks was given.
 if test ${enable_sanity_checks+y}
 then :
diff --git a/configure.ac b/configure.ac
index bdc385d03c..d4d5dcf6a1 100644
--- a/configure.ac
+++ b/configure.ac
@@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
 	    [timeoutfactor=1])
 AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
 
+man_pages_version=6.7
+
+AC_ARG_WITH([man-pages],
+	    AS_HELP_STRING([--with-man-pages=VERSION],
+			   [tie manual to a specific man-pages version]),
+	    [man_pages_version=$withval],
+	    [])
+AC_SUBST(man_pages_version)
+
 AC_ARG_ENABLE([sanity-checks],
 	      AS_HELP_STRING([--disable-sanity-checks],
 			     [really do not use threads (should not be used except in special situations) @<:@default=yes@:>@]),
diff --git a/manual/Makefile b/manual/Makefile
index b5fda4a7ae..1d5b557fa8 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
 
 # Generated files directly included from libc.texinfo.
 libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
-		      libm-err.texi version.texi pkgvers.texi
+		      libm-err.texi version.texi pkgvers.texi \
+		      syscalls.texi syscallsc.texi
 
 # Add path to build dir for generated files
 texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
@@ -117,6 +118,7 @@ $(objpfx)stamp-pkgvers: $(common-objpfx)config.make
 	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
 	fi
 	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
+	echo "@set man_pages_version $(man-pages-version)" >> $(objpfx)pkgvers-tmp; \
 	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
 	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
 	touch $@
@@ -138,6 +140,31 @@ $(objpfx)%.c.texi: examples/%.c
 	    $< | expand > $@.new
 	mv -f $@.new $@
 
+# Generate a list of wrapped syscalls
+$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
+$(objpfx)stamp-syscalls: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e '/[ \t]C/d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscalls-tmp
+	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
+	touch $@
+# Cancelled syscalls
+$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
+$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e '/[ \t]C/!d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscallsc-tmp
+	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
+	touch $@
+
 $(objpfx)%.info: %.texinfo
 	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
 
diff --git a/manual/startup.texi b/manual/startup.texi
index 96a7a472bb..f7de238c3e 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -690,7 +690,30 @@ you don't need to know about it because you can just use @theglibc{}'s
 @code{chmod} function.
 
 @cindex kernel call
-System calls are sometimes called kernel calls.
+System calls are sometimes called syscalls or kernel calls, and this
+interface is mostly a purely mechanical translation from the kernel's
+ABI to the C ABI. For the set of syscalls where we do not guarantee
+POSIX Thread cancellation the wrappers only organize the incoming
+arguments from the C calling convention to the calling convention of
+the target kernel. For the set of syscalls where we provided POSIX
+Thread cancellation the wrappers set some internal state in the
+library to support cancellation, but this does not impact the
+behaviour of the syscall provided by the kernel.
+
+@Theglibc{} includes by reference the Linux man-pages
+@value{man_pages_version} documentation to document the listed
+syscalls for the Linux kernel. For reference purposes only the latest
+@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
+documentation can be accessed from the
+@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
+has more specific documentation in this manual that more specific
+documentation is considered authoritative.
+
+Non-cancellable system calls:
+@include{syscalls.texi}
+
+Cancellable system calls:
+@include{syscallsc.texi}
 
 However, there are times when you want to make a system call explicitly,
 and for that, @theglibc{} provides the @code{syscall} function.

Re: [patch v2] manual: add syscall list

[Alejandro Colomar]

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

Hi DJ,

On Mon, May 20, 2024 at 05:43:43PM GMT, DJ Delorie wrote:
> 
> [Found a spot where we documneted syscall() and there was a natural
> place to insert these docs there.  Defaulted to man-pages 6.7 (current
> rawhide) as I have no reason to pick any other version.  DJ]

Current upstream is 6.8; you may want to choose that one.

> Default version of man-pages is in configure.ac but can be overridden
> by --with-man-pages=X.Y
> 
> diff --git a/config.make.in b/config.make.in
> index 55e8b7563b..36096881b7 100644
> --- a/config.make.in
> +++ b/config.make.in
> @@ -91,6 +91,7 @@ use-nscd = @use_nscd@
>  build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
>  build-pt-chown = @build_pt_chown@
>  pthread-in-libc = @pthread_in_libc@
> +man-pages-version = @man_pages_version@
>  
>  # Build tools.
>  CC = @CC@
> diff --git a/configure b/configure
> index 432e40a592..87b99f0c86 100755
> --- a/configure
> +++ b/configure
> @@ -706,6 +706,7 @@ force_install
>  bindnow
>  hardcoded_path_in_tests
>  enable_timezone_tools
> +man_pages_version
>  rtld_early_cflags
>  extra_nonshared_cflags
>  sysheaders
> @@ -787,6 +788,7 @@ with_headers
>  with_nonshared_cflags
>  with_rtld_early_cflags
>  with_timeoutfactor
> +with_man_pages
>  enable_sanity_checks
>  enable_shared
>  enable_profile
> @@ -1509,6 +1511,8 @@ Optional Packages:
>                            build early initialization with additional CFLAGS
>    --with-timeoutfactor=NUM
>                            specify an integer to scale the timeout
> +  --with-man-pages=VERSION
> +                          tie manual to a specific man-pages version
>    --with-cpu=CPU          select code for CPU variant
>  
>  Some influential environment variables:
> @@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
>  then :
>    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++11 features" >&5
>  printf %s "checking for $CXX option to enable C++11 features... " >&6; }
> -if test ${ac_cv_prog_cxx_cxx11+y}
> +if test ${ac_cv_prog_cxx_11+y}
>  then :
>    printf %s "(cached) " >&6
>  else $as_nop
> -  ac_cv_prog_cxx_cxx11=no
> +  ac_cv_prog_cxx_11=no

Is this necessary in this patch?

>  ac_save_CXX=$CXX
>  cat confdefs.h - <<_ACEOF >conftest.$ac_ext
>  /* end confdefs.h.  */
> @@ -4137,11 +4141,11 @@ if test x$ac_prog_cxx_stdcxx = xno
>  then :
>    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++98 features" >&5
>  printf %s "checking for $CXX option to enable C++98 features... " >&6; }
> -if test ${ac_cv_prog_cxx_cxx98+y}
> +if test ${ac_cv_prog_cxx_98+y}
>  then :
>    printf %s "(cached) " >&6
>  else $as_nop
> -  ac_cv_prog_cxx_cxx98=no
> +  ac_cv_prog_cxx_98=no

Same here.

>  ac_save_CXX=$CXX
>  cat confdefs.h - <<_ACEOF >conftest.$ac_ext
>  /* end confdefs.h.  */
> @@ -4374,6 +4378,17 @@ fi
>  printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
>  
>  
> +man_pages_version=6.7
> +
> +
> +# Check whether --with-man-pages was given.
> +if test ${with_man_pages+y}
> +then :
> +  withval=$with_man_pages; man_pages_version=$withval
> +fi
> +
> +
> +
>  # Check whether --enable-sanity-checks was given.
>  if test ${enable_sanity_checks+y}
>  then :
> diff --git a/configure.ac b/configure.ac
> index bdc385d03c..d4d5dcf6a1 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
>  	    [timeoutfactor=1])
>  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
>  
> +man_pages_version=6.7
> +
> +AC_ARG_WITH([man-pages],
> +	    AS_HELP_STRING([--with-man-pages=VERSION],
> +			   [tie manual to a specific man-pages version]),
> +	    [man_pages_version=$withval],
> +	    [])
> +AC_SUBST(man_pages_version)
> +
>  AC_ARG_ENABLE([sanity-checks],
>  	      AS_HELP_STRING([--disable-sanity-checks],
>  			     [really do not use threads (should not be used except in special situations) @<:@default=yes@:>@]),
> diff --git a/manual/Makefile b/manual/Makefile
> index b5fda4a7ae..1d5b557fa8 100644
> --- a/manual/Makefile
> +++ b/manual/Makefile
> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
>  
>  # Generated files directly included from libc.texinfo.
>  libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
> -		      libm-err.texi version.texi pkgvers.texi
> +		      libm-err.texi version.texi pkgvers.texi \
> +		      syscalls.texi syscallsc.texi
>  
>  # Add path to build dir for generated files
>  texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
> @@ -117,6 +118,7 @@ $(objpfx)stamp-pkgvers: $(common-objpfx)config.make
>  	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
>  	fi
>  	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
> +	echo "@set man_pages_version $(man-pages-version)" >> $(objpfx)pkgvers-tmp; \
>  	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
>  	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
>  	touch $@
> @@ -138,6 +140,31 @@ $(objpfx)%.c.texi: examples/%.c
>  	    $< | expand > $@.new
>  	mv -f $@.new $@
>  
> +# Generate a list of wrapped syscalls
> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \
> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscalls-tmp
> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> +	touch $@
> +# Cancelled syscalls
> +$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
> +$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \
> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/!d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscallsc-tmp
> +	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
> +	touch $@
> +
>  $(objpfx)%.info: %.texinfo
>  	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
>  
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 96a7a472bb..f7de238c3e 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -690,7 +690,30 @@ you don't need to know about it because you can just use @theglibc{}'s
>  @code{chmod} function.
>  
>  @cindex kernel call
> -System calls are sometimes called kernel calls.
> +System calls are sometimes called syscalls or kernel calls, and this
> +interface is mostly a purely mechanical translation from the kernel's
> +ABI to the C ABI. For the set of syscalls where we do not guarantee
> +POSIX Thread cancellation the wrappers only organize the incoming
> +arguments from the C calling convention to the calling convention of
> +the target kernel. For the set of syscalls where we provided POSIX
> +Thread cancellation the wrappers set some internal state in the
> +library to support cancellation, but this does not impact the
> +behaviour of the syscall provided by the kernel.

I would suggest using semantic newlines in your manual for new
additions.  It helps reduce diffs.

$ 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 sentences,
     clauses, or phrases.

> +
> +@Theglibc{} includes by reference the Linux man-pages
> +@value{man_pages_version} documentation to document the listed
> +syscalls for the Linux kernel. For reference purposes only the latest
> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
> +documentation can be accessed from the
> +@uref{https://www.kernel.org,Linux kernel} website.

We publish online manual pages in PDF format, in case you prefer to link
to that.

<https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/>
<https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.8.pdf>

> Where the syscall
> +has more specific documentation in this manual that more specific
> +documentation is considered authoritative.
> +
> +Non-cancellable system calls:
> +@include{syscalls.texi}
> +
> +Cancellable system calls:
> +@include{syscallsc.texi}
>  
>  However, there are times when you want to make a system call explicitly,
>  and for that, @theglibc{} provides the @code{syscall} function.
> 

Other than that, LGTM.  Feel free to add my

Acked-by: Alejandro Colomar <alx@kernel.org>

regardless of my comments above.


Have a lovely night!
Alex

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

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

Re: [patch v2] manual: add syscall list

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> Current upstream is 6.8; you may want to choose that one.

Done!

>> -  ac_cv_prog_cxx_cxx11=no
>> +  ac_cv_prog_cxx_11=no
>
> Is this necessary in this patch?

I just ran autoconf and it included this change.  One could argue either
way - do you minimise the change, or keep it close to generated?

> I would suggest using semantic newlines in your manual for new
> additions.  It helps reduce diffs.

I'll abide by whatever the glibc community wants, but I've long gotten
used to emacs-formatted paragraphs and reading patches therein.

>> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
>> +documentation can be accessed from the
>> +@uref{https://www.kernel.org,Linux kernel} website.
>
> We publish online manual pages in PDF format, in case you prefer to link
> to that.

I have no preference but I bet Carlos does.

> Other than that, LGTM.  Feel free to add my
>
> Acked-by: Alejandro Colomar <alx@kernel.org>

We use Reviewed-by for that but I'll add yours.  Thanks!

Re: [patch v2] manual: add syscall list

[Alejandro Colomar]

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

Hi DJ,

On Mon, May 20, 2024 at 09:12:38PM GMT, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > Other than that, LGTM.  Feel free to add my
> >
> > Acked-by: Alejandro Colomar <alx@kernel.org>
> 
> We use Reviewed-by for that but I'll add yours.  Thanks!

I use Reviewed-by for when I agree with the idea and also the code.
In this case, since I have almost no idea of autotools, I don't
understand the code, so I couldn't say I reviewed it.  :-)
But hmm, the code is so small, that I guess I could say Reviewed-by.
Feel free to transform it to Reviewed-by.  The only caveat is that it's
been reviewed by someone who's hopeless at autotools.

Have a lovely day!
Alex

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

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

Re: [patch v2] manual: add syscall list

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> I use Reviewed-by for when I agree with the idea and also the code.
> In this case, since I have almost no idea of autotools, I don't
> understand the code, so I couldn't say I reviewed it.  :-)
> But hmm, the code is so small, that I guess I could say Reviewed-by.
> Feel free to transform it to Reviewed-by.  The only caveat is that it's
> been reviewed by someone who's hopeless at autotools.

Noted.  I'm waiting for a second review anyway, for other reasons.  But
even a partial review is helpful!  And everyone who even partially
reviews should still get credit for their efforts.

[patch v3] manual: add syscall list

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> Current upstream is 6.8; you may want to choose that one.

[v3 has the above, plus a syntax change to allow .info files, hopefully
this one will pass CI]

Default version of man-pages is in configure.ac but can be overridden
by --with-man-pages=X.Y

Reviewed-by: Alejandro Colomar <alx@kernel.org>

diff --git a/config.make.in b/config.make.in
index 55e8b7563b..36096881b7 100644
--- a/config.make.in
+++ b/config.make.in
@@ -91,6 +91,7 @@ use-nscd = @use_nscd@
 build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
 build-pt-chown = @build_pt_chown@
 pthread-in-libc = @pthread_in_libc@
+man-pages-version = @man_pages_version@
 
 # Build tools.
 CC = @CC@
diff --git a/configure b/configure
index 432e40a592..73ec5cdd66 100755
--- a/configure
+++ b/configure
@@ -706,6 +706,7 @@ force_install
 bindnow
 hardcoded_path_in_tests
 enable_timezone_tools
+man_pages_version
 rtld_early_cflags
 extra_nonshared_cflags
 sysheaders
@@ -787,6 +788,7 @@ with_headers
 with_nonshared_cflags
 with_rtld_early_cflags
 with_timeoutfactor
+with_man_pages
 enable_sanity_checks
 enable_shared
 enable_profile
@@ -1509,6 +1511,8 @@ Optional Packages:
                           build early initialization with additional CFLAGS
   --with-timeoutfactor=NUM
                           specify an integer to scale the timeout
+  --with-man-pages=VERSION
+                          tie manual to a specific man-pages version
   --with-cpu=CPU          select code for CPU variant
 
 Some influential environment variables:
@@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
 then :
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++11 features" >&5
 printf %s "checking for $CXX option to enable C++11 features... " >&6; }
-if test ${ac_cv_prog_cxx_cxx11+y}
+if test ${ac_cv_prog_cxx_11+y}
 then :
   printf %s "(cached) " >&6
 else $as_nop
-  ac_cv_prog_cxx_cxx11=no
+  ac_cv_prog_cxx_11=no
 ac_save_CXX=$CXX
 cat confdefs.h - <<_ACEOF >conftest.$ac_ext
 /* end confdefs.h.  */
@@ -4137,11 +4141,11 @@ if test x$ac_prog_cxx_stdcxx = xno
 then :
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++98 features" >&5
 printf %s "checking for $CXX option to enable C++98 features... " >&6; }
-if test ${ac_cv_prog_cxx_cxx98+y}
+if test ${ac_cv_prog_cxx_98+y}
 then :
   printf %s "(cached) " >&6
 else $as_nop
-  ac_cv_prog_cxx_cxx98=no
+  ac_cv_prog_cxx_98=no
 ac_save_CXX=$CXX
 cat confdefs.h - <<_ACEOF >conftest.$ac_ext
 /* end confdefs.h.  */
@@ -4374,6 +4378,17 @@ fi
 printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
 
 
+man_pages_version=6.8
+
+
+# Check whether --with-man-pages was given.
+if test ${with_man_pages+y}
+then :
+  withval=$with_man_pages; man_pages_version=$withval
+fi
+
+
+
 # Check whether --enable-sanity-checks was given.
 if test ${enable_sanity_checks+y}
 then :
diff --git a/configure.ac b/configure.ac
index bdc385d03c..bdd82a8356 100644
--- a/configure.ac
+++ b/configure.ac
@@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
 	    [timeoutfactor=1])
 AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
 
+man_pages_version=6.8
+
+AC_ARG_WITH([man-pages],
+	    AS_HELP_STRING([--with-man-pages=VERSION],
+			   [tie manual to a specific man-pages version]),
+	    [man_pages_version=$withval],
+	    [])
+AC_SUBST(man_pages_version)
+
 AC_ARG_ENABLE([sanity-checks],
 	      AS_HELP_STRING([--disable-sanity-checks],
 			     [really do not use threads (should not be used except in special situations) @<:@default=yes@:>@]),
diff --git a/manual/Makefile b/manual/Makefile
index b5fda4a7ae..1d5b557fa8 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
 
 # Generated files directly included from libc.texinfo.
 libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
-		      libm-err.texi version.texi pkgvers.texi
+		      libm-err.texi version.texi pkgvers.texi \
+		      syscalls.texi syscallsc.texi
 
 # Add path to build dir for generated files
 texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
@@ -117,6 +118,7 @@ $(objpfx)stamp-pkgvers: $(common-objpfx)config.make
 	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
 	fi
 	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
+	echo "@set man_pages_version $(man-pages-version)" >> $(objpfx)pkgvers-tmp; \
 	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
 	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
 	touch $@
@@ -138,6 +140,31 @@ $(objpfx)%.c.texi: examples/%.c
 	    $< | expand > $@.new
 	mv -f $@.new $@
 
+# Generate a list of wrapped syscalls
+$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
+$(objpfx)stamp-syscalls: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e '/[ \t]C/d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscalls-tmp
+	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
+	touch $@
+# Cancelled syscalls
+$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
+$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e '/[ \t]C/!d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscallsc-tmp
+	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
+	touch $@
+
 $(objpfx)%.info: %.texinfo
 	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
 
diff --git a/manual/startup.texi b/manual/startup.texi
index 96a7a472bb..527e4d4795 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -690,7 +690,30 @@ you don't need to know about it because you can just use @theglibc{}'s
 @code{chmod} function.
 
 @cindex kernel call
-System calls are sometimes called kernel calls.
+System calls are sometimes called syscalls or kernel calls, and this
+interface is mostly a purely mechanical translation from the kernel's
+ABI to the C ABI. For the set of syscalls where we do not guarantee
+POSIX Thread cancellation the wrappers only organize the incoming
+arguments from the C calling convention to the calling convention of
+the target kernel. For the set of syscalls where we provided POSIX
+Thread cancellation the wrappers set some internal state in the
+library to support cancellation, but this does not impact the
+behaviour of the syscall provided by the kernel.
+
+@Theglibc{} includes by reference the Linux man-pages
+@value{man_pages_version} documentation to document the listed
+syscalls for the Linux kernel. For reference purposes only the latest
+@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
+documentation can be accessed from the
+@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
+has more specific documentation in this manual that more specific
+documentation is considered authoritative.
+
+Non-cancellable system calls:
+@include syscalls.texi
+
+Cancellable system calls:
+@include syscallsc.texi
 
 However, there are times when you want to make a system call explicitly,
 and for that, @theglibc{} provides the @code{syscall} function.

Re: [patch v3] manual: add syscall list

[Carlos O'Donell]

On 5/21/24 4:04 PM, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
>> Current upstream is 6.8; you may want to choose that one.

Passes CI/CD:
https://patchwork.sourceware.org/project/glibc/patch/xn5xv77wym.fsf@greed.delorie.com/

Thank you!

Needs a few changes IMO.

Looking forward to v4.

> [v3 has the above, plus a syntax change to allow .info files, hopefully
> this one will pass CI]
> 
> Default version of man-pages is in configure.ac but can be overridden
> by --with-man-pages=X.Y
> 
> Reviewed-by: Alejandro Colomar <alx@kernel.org>
> 
> diff --git a/config.make.in b/config.make.in
> index 55e8b7563b..36096881b7 100644
> --- a/config.make.in
> +++ b/config.make.in
> @@ -91,6 +91,7 @@ use-nscd = @use_nscd@
>  build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
>  build-pt-chown = @build_pt_chown@
>  pthread-in-libc = @pthread_in_libc@
> +man-pages-version = @man_pages_version@

OK. Encoded version.

>  
>  # Build tools.
>  CC = @CC@
> diff --git a/configure b/configure
> index 432e40a592..73ec5cdd66 100755
> --- a/configure
> +++ b/configure
> @@ -706,6 +706,7 @@ force_install
>  bindnow
>  hardcoded_path_in_tests
>  enable_timezone_tools
> +man_pages_version
>  rtld_early_cflags
>  extra_nonshared_cflags
>  sysheaders
> @@ -787,6 +788,7 @@ with_headers
>  with_nonshared_cflags
>  with_rtld_early_cflags
>  with_timeoutfactor
> +with_man_pages
>  enable_sanity_checks
>  enable_shared
>  enable_profile
> @@ -1509,6 +1511,8 @@ Optional Packages:
>                            build early initialization with additional CFLAGS
>    --with-timeoutfactor=NUM
>                            specify an integer to scale the timeout
> +  --with-man-pages=VERSION
> +                          tie manual to a specific man-pages version
>    --with-cpu=CPU          select code for CPU variant
>  
>  Some influential environment variables:
> @@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
>  then :
>    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++11 features" >&5
>  printf %s "checking for $CXX option to enable C++11 features... " >&6; }
> -if test ${ac_cv_prog_cxx_cxx11+y}
> +if test ${ac_cv_prog_cxx_11+y}
>  then :
>    printf %s "(cached) " >&6
>  else $as_nop
> -  ac_cv_prog_cxx_cxx11=no
> +  ac_cv_prog_cxx_11=no
>  ac_save_CXX=$CXX
>  cat confdefs.h - <<_ACEOF >conftest.$ac_ext
>  /* end confdefs.h.  */
> @@ -4137,11 +4141,11 @@ if test x$ac_prog_cxx_stdcxx = xno
>  then :
>    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++98 features" >&5
>  printf %s "checking for $CXX option to enable C++98 features... " >&6; }
> -if test ${ac_cv_prog_cxx_cxx98+y}
> +if test ${ac_cv_prog_cxx_98+y}
>  then :
>    printf %s "(cached) " >&6
>  else $as_nop
> -  ac_cv_prog_cxx_cxx98=no
> +  ac_cv_prog_cxx_98=no
>  ac_save_CXX=$CXX
>  cat confdefs.h - <<_ACEOF >conftest.$ac_ext
>  /* end confdefs.h.  */
> @@ -4374,6 +4378,17 @@ fi
>  printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
>  
>  
> +man_pages_version=6.8
> +
> +
> +# Check whether --with-man-pages was given.
> +if test ${with_man_pages+y}
> +then :
> +  withval=$with_man_pages; man_pages_version=$withval
> +fi
> +
> +
> +
>  # Check whether --enable-sanity-checks was given.
>  if test ${enable_sanity_checks+y}
>  then :
> diff --git a/configure.ac b/configure.ac
> index bdc385d03c..bdd82a8356 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
>  	    [timeoutfactor=1])
>  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
>  
> +man_pages_version=6.8

OK. Good, base version we audited up to.

> +
> +AC_ARG_WITH([man-pages],
> +	    AS_HELP_STRING([--with-man-pages=VERSION],
> +			   [tie manual to a specific man-pages version]),
> +	    [man_pages_version=$withval],
> +	    [])
> +AC_SUBST(man_pages_version)
> +
>  AC_ARG_ENABLE([sanity-checks],
>  	      AS_HELP_STRING([--disable-sanity-checks],
>  			     [really do not use threads (should not be used except in special situations) @<:@default=yes@:>@]),
> diff --git a/manual/Makefile b/manual/Makefile
> index b5fda4a7ae..1d5b557fa8 100644
> --- a/manual/Makefile
> +++ b/manual/Makefile
> @@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
>  
>  # Generated files directly included from libc.texinfo.
>  libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
> -		      libm-err.texi version.texi pkgvers.texi
> +		      libm-err.texi version.texi pkgvers.texi \
> +		      syscalls.texi syscallsc.texi

OK. Two new texi files.

>  
>  # Add path to build dir for generated files
>  texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
> @@ -117,6 +118,7 @@ $(objpfx)stamp-pkgvers: $(common-objpfx)config.make
>  	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
>  	fi
>  	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
> +	echo "@set man_pages_version $(man-pages-version)" >> $(objpfx)pkgvers-tmp; \

OK.

>  	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
>  	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
>  	touch $@
> @@ -138,6 +140,31 @@ $(objpfx)%.c.texi: examples/%.c
>  	    $< | expand > $@.new
>  	mv -f $@.new $@
>  
> +# Generate a list of wrapped syscalls

s/wrapped syscalls/syscall wrappers (non-cancellable)... /g

> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \

OK. This scans *all targets* and generates *all syscalls* regardless of if the
configuration is used or unused. This makes the list architecture agnostic. We
will need to say something about that later.

> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscalls-tmp
> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> +	touch $@
> +# Cancelled syscalls

s/Cancelled/... and cancellable syscall wrappers/g

> +$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
> +$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \
> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/!d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscallsc-tmp
> +	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
> +	touch $@
> +
>  $(objpfx)%.info: %.texinfo
>  	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
>  
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 96a7a472bb..527e4d4795 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -690,7 +690,30 @@ you don't need to know about it because you can just use @theglibc{}'s
>  @code{chmod} function.
>  
>  @cindex kernel call
> -System calls are sometimes called kernel calls.
> +System calls are sometimes called syscalls or kernel calls, and this
> +interface is mostly a purely mechanical translation from the kernel's
> +ABI to the C ABI. For the set of syscalls where we do not guarantee
> +POSIX Thread cancellation the wrappers only organize the incoming
> +arguments from the C calling convention to the calling convention of
> +the target kernel. For the set of syscalls where we provided POSIX
> +Thread cancellation the wrappers set some internal state in the
> +library to support cancellation, but this does not impact the
> +behaviour of the syscall provided by the kernel.
> +
> +@Theglibc{} includes by reference the Linux man-pages
> +@value{man_pages_version} documentation to document the listed
> +syscalls for the Linux kernel. For reference purposes only the latest
> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
> +documentation can be accessed from the
> +@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
> +has more specific documentation in this manual that more specific
> +documentation is considered authoritative.

This needs extra information to say that this list covers all targets provided by glibc.

When posting v4 may you please post a PDF of the final results from `make pdf?`

Thank you!

> +
> +Non-cancellable system calls:
> +@include syscalls.texi
> +
> +Cancellable system calls:
> +@include syscallsc.texi
>  
>  However, there are times when you want to make a system call explicitly,
>  and for that, @theglibc{} provides the @code{syscall} function.
> 

-- 
Cheers,
Carlos.

Re: [patch v3] manual: add syscall list

[DJ Delorie]

"Carlos O'Donell" <carlos@redhat.com> writes:
>> +# Generate a list of wrapped syscalls
>
> s/wrapped syscalls/syscall wrappers (non-cancellable)... /g

Fixed.

> s/Cancelled/... and cancellable syscall wrappers/g

Fixed.

>> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
>> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
>> +	cat `find ../sysdeps -name syscalls.list -print` \
>
> OK. This scans *all targets* and generates *all syscalls* regardless of if the
> configuration is used or unused. This makes the list architecture agnostic. We
> will need to say something about that later.
>
>> +documentation is considered authoritative.
>
> This needs extra information to say that this list covers all targets provided by glibc.

I changed the prelude to each list to be such:

  Here is the list of all potential non-cancellable system calls, across
  all configurations of @theglibc():

  Here's the corresponding list of cancellable system calls:

I think that covers both these requests.

> When posting v4 may you please post a PDF of the final results from `make pdf?`

I'll attach it in a separate email in case the mail filters are having a
bad day ;-)

[patch v4] manual: add syscall list

[DJ Delorie]

[v4 cleans up comment text and list prefixes]

Default version of man-pages is in configure.ac but can be overridden
by --with-man-pages=X.Y

Reviewed-by: Alejandro Colomar <alx@kernel.org>

diff --git a/config.make.in b/config.make.in
index 55e8b7563b..36096881b7 100644
--- a/config.make.in
+++ b/config.make.in
@@ -91,6 +91,7 @@ use-nscd = @use_nscd@
 build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
 build-pt-chown = @build_pt_chown@
 pthread-in-libc = @pthread_in_libc@
+man-pages-version = @man_pages_version@
 
 # Build tools.
 CC = @CC@
diff --git a/configure b/configure
index 432e40a592..73ec5cdd66 100755
--- a/configure
+++ b/configure
@@ -706,6 +706,7 @@ force_install
 bindnow
 hardcoded_path_in_tests
 enable_timezone_tools
+man_pages_version
 rtld_early_cflags
 extra_nonshared_cflags
 sysheaders
@@ -787,6 +788,7 @@ with_headers
 with_nonshared_cflags
 with_rtld_early_cflags
 with_timeoutfactor
+with_man_pages
 enable_sanity_checks
 enable_shared
 enable_profile
@@ -1509,6 +1511,8 @@ Optional Packages:
                           build early initialization with additional CFLAGS
   --with-timeoutfactor=NUM
                           specify an integer to scale the timeout
+  --with-man-pages=VERSION
+                          tie manual to a specific man-pages version
   --with-cpu=CPU          select code for CPU variant
 
 Some influential environment variables:
@@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
 then :
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++11 features" >&5
 printf %s "checking for $CXX option to enable C++11 features... " >&6; }
-if test ${ac_cv_prog_cxx_cxx11+y}
+if test ${ac_cv_prog_cxx_11+y}
 then :
   printf %s "(cached) " >&6
 else $as_nop
-  ac_cv_prog_cxx_cxx11=no
+  ac_cv_prog_cxx_11=no
 ac_save_CXX=$CXX
 cat confdefs.h - <<_ACEOF >conftest.$ac_ext
 /* end confdefs.h.  */
@@ -4137,11 +4141,11 @@ if test x$ac_prog_cxx_stdcxx = xno
 then :
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX option to enable C++98 features" >&5
 printf %s "checking for $CXX option to enable C++98 features... " >&6; }
-if test ${ac_cv_prog_cxx_cxx98+y}
+if test ${ac_cv_prog_cxx_98+y}
 then :
   printf %s "(cached) " >&6
 else $as_nop
-  ac_cv_prog_cxx_cxx98=no
+  ac_cv_prog_cxx_98=no
 ac_save_CXX=$CXX
 cat confdefs.h - <<_ACEOF >conftest.$ac_ext
 /* end confdefs.h.  */
@@ -4374,6 +4378,17 @@ fi
 printf "%s\n" "#define TIMEOUTFACTOR $timeoutfactor" >>confdefs.h
 
 
+man_pages_version=6.8
+
+
+# Check whether --with-man-pages was given.
+if test ${with_man_pages+y}
+then :
+  withval=$with_man_pages; man_pages_version=$withval
+fi
+
+
+
 # Check whether --enable-sanity-checks was given.
 if test ${enable_sanity_checks+y}
 then :
diff --git a/configure.ac b/configure.ac
index bdc385d03c..bdd82a8356 100644
--- a/configure.ac
+++ b/configure.ac
@@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
 	    [timeoutfactor=1])
 AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
 
+man_pages_version=6.8
+
+AC_ARG_WITH([man-pages],
+	    AS_HELP_STRING([--with-man-pages=VERSION],
+			   [tie manual to a specific man-pages version]),
+	    [man_pages_version=$withval],
+	    [])
+AC_SUBST(man_pages_version)
+
 AC_ARG_ENABLE([sanity-checks],
 	      AS_HELP_STRING([--disable-sanity-checks],
 			     [really do not use threads (should not be used except in special situations) @<:@default=yes@:>@]),
diff --git a/manual/Makefile b/manual/Makefile
index b5fda4a7ae..d4ef8f8dd7 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -55,7 +55,8 @@ examples = $(filter %.c.texi, $(texis))
 
 # Generated files directly included from libc.texinfo.
 libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
-		      libm-err.texi version.texi pkgvers.texi
+		      libm-err.texi version.texi pkgvers.texi \
+		      syscalls.texi syscallsc.texi
 
 # Add path to build dir for generated files
 texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
@@ -117,6 +118,7 @@ $(objpfx)stamp-pkgvers: $(common-objpfx)config.make
 	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
 	fi
 	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
+	echo "@set man_pages_version $(man-pages-version)" >> $(objpfx)pkgvers-tmp; \
 	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
 	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
 	touch $@
@@ -138,6 +140,32 @@ $(objpfx)%.c.texi: examples/%.c
 	    $< | expand > $@.new
 	mv -f $@.new $@
 
+# Generate a list of potential syscall wrappers (non-cancellable)
+$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
+$(objpfx)stamp-syscalls: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e '/[ \t]C/d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscalls-tmp
+	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
+	touch $@
+
+# Generate a list of potential syscall wrappers (cancellable)
+$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
+$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
+	cat `find ../sysdeps -name syscalls.list -print` \
+	| sed -e '/^[^_a-zA-Z]/d' \
+	      -e '/[ \t]C/!d' \
+	      -e 's/[ \t].*//' \
+	      -e 's/^/@code{/; s/$$/}/' \
+	| sort -u \
+	> $(objpfx)syscallsc-tmp
+	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
+	touch $@
+
 $(objpfx)%.info: %.texinfo
 	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
 
diff --git a/manual/startup.texi b/manual/startup.texi
index 96a7a472bb..f6e0ab909c 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -690,7 +690,31 @@ you don't need to know about it because you can just use @theglibc{}'s
 @code{chmod} function.
 
 @cindex kernel call
-System calls are sometimes called kernel calls.
+System calls are sometimes called syscalls or kernel calls, and this
+interface is mostly a purely mechanical translation from the kernel's
+ABI to the C ABI. For the set of syscalls where we do not guarantee
+POSIX Thread cancellation the wrappers only organize the incoming
+arguments from the C calling convention to the calling convention of
+the target kernel. For the set of syscalls where we provided POSIX
+Thread cancellation the wrappers set some internal state in the
+library to support cancellation, but this does not impact the
+behaviour of the syscall provided by the kernel.
+
+@Theglibc{} includes by reference the Linux man-pages
+@value{man_pages_version} documentation to document the listed
+syscalls for the Linux kernel. For reference purposes only the latest
+@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
+documentation can be accessed from the
+@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
+has more specific documentation in this manual that more specific
+documentation is considered authoritative.
+
+Here is the list of all potential non-cancellable system calls, across
+all configurations of @theglibc():
+@include syscalls.texi
+
+Here's the corresponding list of cancellable system calls:
+@include syscallsc.texi
 
 However, there are times when you want to make a system call explicitly,
 and for that, @theglibc{} provides the @code{syscall} function.

Re: [patch v4] manual: add syscall list

[DJ Delorie]

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


Here's the generated PDF for it:


[-- Attachment #2: libc manual pdf --]
[-- Type: application/pdf, Size: 4181674 bytes --]

Re: [patch v4] manual: add syscall list

[Florian Weimer]

* DJ Delorie:

> diff --git a/manual/startup.texi b/manual/startup.texi
> index 96a7a472bb..f6e0ab909c 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -690,7 +690,31 @@ you don't need to know about it because you can just use @theglibc{}'s
>  @code{chmod} function.
>  
>  @cindex kernel call
> -System calls are sometimes called kernel calls.
> +System calls are sometimes called syscalls or kernel calls, and this
> +interface is mostly a purely mechanical translation from the kernel's
> +ABI to the C ABI. For the set of syscalls where we do not guarantee
> +POSIX Thread cancellation the wrappers only organize the incoming
> +arguments from the C calling convention to the calling convention of
> +the target kernel. For the set of syscalls where we provided POSIX
> +Thread cancellation the wrappers set some internal state in the
> +library to support cancellation, but this does not impact the
> +behaviour of the syscall provided by the kernel.
> +
> +@Theglibc{} includes by reference the Linux man-pages
> +@value{man_pages_version} documentation to document the listed
> +syscalls for the Linux kernel. For reference purposes only the latest
> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
> +documentation can be accessed from the
> +@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
> +has more specific documentation in this manual that more specific
> +documentation is considered authoritative.
> +
> +Here is the list of all potential non-cancellable system calls, across
> +all configurations of @theglibc():

@theglibc() should be @theglibc{} (typographical error).

> +@include syscalls.texi

Should the list be separated by commas?  It's currently space-separated
only.

The list still includes getuid, which is most emphatically not a single
system call in multi-threaded programs, not on Linux and not on Hurd.

> +Here's the corresponding list of cancellable system calls:
> +@include syscallsc.texi

Unfortunately, this now gives the impression that the syscall function
described below implements a cancellable system call when called for
SYS_read (for example).  But that's not accurate.  System calls invoked
through the syscall function are never cancellable.

Maybe add to the commit message why we are adding this?  Is this an
attempt to achieve completeness of the manual by referencing the manual
page for certain functions we do not document?  Maybe it would be more
approriate to add @deftypefn directives for those specific functions,
with a stub that refers to the corresponding man-pages URL?

Do we have a rendered version of the current development version that we
can point people to for review purposes?

Thanks,
Florian

Re: [patch v4] manual: add syscall list

[Florian Weimer]

* Florian Weimer:

> * DJ Delorie:
>
>> diff --git a/manual/startup.texi b/manual/startup.texi
>> index 96a7a472bb..f6e0ab909c 100644
>> --- a/manual/startup.texi
>> +++ b/manual/startup.texi
>> @@ -690,7 +690,31 @@ you don't need to know about it because you can just use @theglibc{}'s
>>  @code{chmod} function.
>>  
>>  @cindex kernel call
>> -System calls are sometimes called kernel calls.
>> +System calls are sometimes called syscalls or kernel calls, and this
>> +interface is mostly a purely mechanical translation from the kernel's
>> +ABI to the C ABI. For the set of syscalls where we do not guarantee
>> +POSIX Thread cancellation the wrappers only organize the incoming
>> +arguments from the C calling convention to the calling convention of
>> +the target kernel. For the set of syscalls where we provided POSIX
>> +Thread cancellation the wrappers set some internal state in the
>> +library to support cancellation, but this does not impact the
>> +behaviour of the syscall provided by the kernel.
>> +
>> +@Theglibc{} includes by reference the Linux man-pages
>> +@value{man_pages_version} documentation to document the listed
>> +syscalls for the Linux kernel. For reference purposes only the latest
>> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
>> +documentation can be accessed from the
>> +@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
>> +has more specific documentation in this manual that more specific
>> +documentation is considered authoritative.
>> +
>> +Here is the list of all potential non-cancellable system calls, across
>> +all configurations of @theglibc():
>
> @theglibc() should be @theglibc{} (typographical error).
>
>> +@include syscalls.texi
>
> Should the list be separated by commas?  It's currently space-separated
> only.
>
> The list still includes getuid, which is most emphatically not a single
> system call in multi-threaded programs, not on Linux and not on Hurd.

Actually setuid, but fortunately it's in the list as well.

>
>> +Here's the corresponding list of cancellable system calls:
>> +@include syscallsc.texi
>
> Unfortunately, this now gives the impression that the syscall function
> described below implements a cancellable system call when called for
> SYS_read (for example).  But that's not accurate.  System calls invoked
> through the syscall function are never cancellable.
>
> Maybe add to the commit message why we are adding this?  Is this an
> attempt to achieve completeness of the manual by referencing the manual
> page for certain functions we do not document?  Maybe it would be more
> approriate to add @deftypefn directives for those specific functions,
> with a stub that refers to the corresponding man-pages URL?
>
> Do we have a rendered version of the current development version that we
> can point people to for review purposes?
>
> Thanks,
> Florian

Re: [patch v4] manual: add syscall list

[DJ Delorie]

Florian Weimer <fweimer@redhat.com> writes:
> @theglibc() should be @theglibc{} (typographical error).

Fixed.

>> +@include syscalls.texi
>
> Should the list be separated by commas?  It's currently space-separated
> only.

The script to generate it would have to be much more complicated to put
commas after every line *except* the last line, and I didn't want to
involve something like perl or python.

> The list still includes getuid, which is most emphatically not a single
> system call in multi-threaded programs, not on Linux and not on Hurd.

As I noted before, I'm all for cleaning up the syscalls.list files, but
this patch is independent of that problem.  setuid is listed as a
wrapped syscall in sysdeps/unix/syscalls.list.  If that's not true,
take it off that list.

>> +Here's the corresponding list of cancellable system calls:
>> +@include syscallsc.texi
>
> Unfortunately, this now gives the impression that the syscall function
> described below implements a cancellable system call when called for
> SYS_read (for example).  But that's not accurate.  System calls invoked
> through the syscall function are never cancellable.

I can add a note about that in the syscall() text.

> Maybe add to the commit message why we are adding this?

We are adding this because the kernel folks don't have authoritative
documentation for their APIs.  The best they have is the man pages
project, which is an independent, volunteer, and cross-OS effort.  Since
glibc is providing wrappers for syscalls, we get blamed for not
documenting *our* APIs (the wrappers).  This "blame" prevents glibc from
being used in certain paperwork-heavy situations.  The only alternative
is to document these functions ourselves, but because of the GFDL we
can't share the man-pages project's efforts.  I'm not sure how to
document that politely ;-)

> Is this an attempt to achieve completeness of the manual by
> referencing the manual page for certain functions we do not document?

No, it's an attempt to achieve completeness by referencing the man pages
for functions we do not *control*.

> Maybe it would be more approriate to add @deftypefn directives for
> those specific functions, with a stub that refers to the corresponding
> man-pages URL?

To do that cleanly, they'd have to be integrated throughout the manual
as each function's purpose deems apropriate.  Plus, the parameters would
still need to be documented or at least enumerated.  Otherwise, it
becomes just a more complex scripting, without real benefit.

> Do we have a rendered version of the current development version that we
> can point people to for review purposes?

I posted a PDF in a separate email.

Re: [patch v4] manual: add syscall list

[DJ Delorie]

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


PDF pages 861-863 ; posting the whole pdf exceeds the lists' message
size limit.


[-- Attachment #2: libc-26.6.pdf --]
[-- Type: application/pdf, Size: 49461 bytes --]

Re: [patch v4] manual: add syscall list

[Alejandro Colomar]

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

Hi DJ,

On Wed, May 22, 2024 at 03:41:04PM GMT, DJ Delorie wrote:
> [v4 cleans up comment text and list prefixes]
> 
> Default version of man-pages is in configure.ac but can be overridden
> by --with-man-pages=X.Y
> 
> Reviewed-by: Alejandro Colomar <alx@kernel.org>
> 

[...]

> +# Generate a list of potential syscall wrappers (non-cancellable)
> +$(objpfx)syscalls.texi: $(objpfx)stamp-syscalls ;
> +$(objpfx)stamp-syscalls: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \

I would change the line above to avoid `` --or $()--, by using xargs(1),
which is simpler, IMO.  While rewriting this line, I'd also remove the
'-print' action since it's the default, and also change -name by a
simpler grep(1):

	find ../sysdeps -type f \
	| grep '/syscalls.list$' \
	| xargs sed ... \

grep(1) is also easier to understand than the many file-name variants
that find(1) has available (and with some luck, spreads the work load to
more CPUs, finishing faster).

> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \

For writing a comma separated list, you can use something similar to a
script I wrote for the git-commit subject prefixes that I use in the
Linux man-pages project:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/scripts/bash_aliases#n146>

For your case, it would be:

	... \
	| sort \
	| uniq \
	| sed 's/$/, /' \
	| tr -d '\n' \
	| sed 's/, $//' \
	> ...

which separates with ", ".  Or if you want ",\n" as the separator, it
would be:

	... \
	| sort \
	| uniq \
	| sed 's/$/,/' \
	| sed '$s/,$//' \
	> ...

No need to use perl(1) nor python(1).  ;)
If you take those snippets, please add

	Co-developed-by: Alejandro Colomar <alx@kernel.org>
	Signed-off-by: Alejandro Colomar <alx@kernel.org>

Have a lovely night!
Alex

> +	> $(objpfx)syscalls-tmp
> +	$(move-if-change) $(objpfx)syscalls-tmp $(objpfx)syscalls.texi
> +	touch $@
> +
> +# Generate a list of potential syscall wrappers (cancellable)
> +$(objpfx)syscallsc.texi: $(objpfx)stamp-syscallsc ;
> +$(objpfx)stamp-syscallsc: $(common-objpfx)config.make
> +	cat `find ../sysdeps -name syscalls.list -print` \
> +	| sed -e '/^[^_a-zA-Z]/d' \
> +	      -e '/[ \t]C/!d' \
> +	      -e 's/[ \t].*//' \
> +	      -e 's/^/@code{/; s/$$/}/' \
> +	| sort -u \
> +	> $(objpfx)syscallsc-tmp
> +	$(move-if-change) $(objpfx)syscallsc-tmp $(objpfx)syscallsc.texi
> +	touch $@
> +
>  $(objpfx)%.info: %.texinfo
>  	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
>  
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 96a7a472bb..f6e0ab909c 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -690,7 +690,31 @@ you don't need to know about it because you can just use @theglibc{}'s
>  @code{chmod} function.
>  
>  @cindex kernel call
> -System calls are sometimes called kernel calls.
> +System calls are sometimes called syscalls or kernel calls, and this
> +interface is mostly a purely mechanical translation from the kernel's
> +ABI to the C ABI. For the set of syscalls where we do not guarantee
> +POSIX Thread cancellation the wrappers only organize the incoming
> +arguments from the C calling convention to the calling convention of
> +the target kernel. For the set of syscalls where we provided POSIX
> +Thread cancellation the wrappers set some internal state in the
> +library to support cancellation, but this does not impact the
> +behaviour of the syscall provided by the kernel.
> +
> +@Theglibc{} includes by reference the Linux man-pages
> +@value{man_pages_version} documentation to document the listed
> +syscalls for the Linux kernel. For reference purposes only the latest
> +@uref{https://www.kernel.org/doc/man-pages/,Linux man-pages Project}
> +documentation can be accessed from the
> +@uref{https://www.kernel.org,Linux kernel} website. Where the syscall
> +has more specific documentation in this manual that more specific
> +documentation is considered authoritative.
> +
> +Here is the list of all potential non-cancellable system calls, across
> +all configurations of @theglibc():
> +@include syscalls.texi
> +
> +Here's the corresponding list of cancellable system calls:
> +@include syscallsc.texi
>  
>  However, there are times when you want to make a system call explicitly,
>  and for that, @theglibc{} provides the @code{syscall} function.
> 

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

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

Re: [patch v4] manual: add syscall list

[Florian Weimer]

* DJ Delorie:

> Florian Weimer <fweimer@redhat.com> writes:
>> @theglibc() should be @theglibc{} (typographical error).
>
> Fixed.
>
>>> +@include syscalls.texi
>>
>> Should the list be separated by commas?  It's currently space-separated
>> only.
>
> The script to generate it would have to be much more complicated to put
> commas after every line *except* the last line, and I didn't want to
> involve something like perl or python.

I think that should do it?

  … | xargs | sed 's/ /, /g' | …

It's not completely reliable in general (-n and -e as initial strings
are special), but it would work in this context.

Thanks,
Florian

Re: [patch v4] manual: add syscall list

[Andreas Schwab]

On Mai 23 2024, Florian Weimer wrote:

> * DJ Delorie:
>
>> Florian Weimer <fweimer@redhat.com> writes:
>>> @theglibc() should be @theglibc{} (typographical error).
>>
>> Fixed.
>>
>>>> +@include syscalls.texi
>>>
>>> Should the list be separated by commas?  It's currently space-separated
>>> only.
>>
>> The script to generate it would have to be much more complicated to put
>> commas after every line *except* the last line, and I didn't want to
>> involve something like perl or python.
>
> I think that should do it?
>
>   … | xargs | sed 's/ /, /g' | …

    ... | sed '$b;s/$/,/' | ...

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: [patch v4] manual: add syscall list

[Zack Weinberg]

On Wed, May 22, 2024, at 3:41 PM, DJ Delorie wrote:
> [v4 cleans up comment text and list prefixes]

I saw something go by earlier about previous reviewers not being
confident in their understanding of the changes to the configure.ac,
so let me jump in and review that part...

> --- a/configure.ac
> +++ b/configure.ac
> @@ -168,6 +168,15 @@ AC_ARG_WITH([timeoutfactor],
>  	    [timeoutfactor=1])
>  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
> 
> +man_pages_version=6.8
> +
> +AC_ARG_WITH([man-pages],
> +	    AS_HELP_STRING([--with-man-pages=VERSION],
> +			   [tie manual to a specific man-pages version]),
> +	    [man_pages_version=$withval],
> +	    [])
> +AC_SUBST(man_pages_version)
> +
>  AC_ARG_ENABLE([sanity-checks],
>  	      AS_HELP_STRING([--disable-sanity-checks],
>  			     [really do not use threads (should not be used except in 

This is fine as is.  I might suggest a tiny change: instead of
setting the default value for man_pages_version above the AC_ARG_WITH,
set it in the action-if-not-given:

>  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
> 
> +AC_ARG_WITH([man-pages],
> +	    AS_HELP_STRING([--with-man-pages=VERSION],
> +			   [tie manual to a specific man-pages version]),
> +	    [man_pages_version=$withval],
> +	    [man_pages_version=6.8])
> +AC_SUBST(man_pages_version)

Also, I wonder if it makes sense to tie the default here to the
default for --enable-kernel, assuming there is one.

I don’t believe there are any strong reasons to M4-quote or not
M4-quote the argument to AC_SUBST, since shell variable names tend not
to be also M4 macro names, so please just make sure the way you did it
is consistent with AC_SUBSTs elsewhere in the file.


> --- a/config.make.in
> +++ b/config.make.in
> @@ -91,6 +91,7 @@ use-nscd = @use_nscd@
>  build-hardcoded-path-in-tests= @hardcoded_path_in_tests@
>  build-pt-chown = @build_pt_chown@
>  pthread-in-libc = @pthread_in_libc@
> +man-pages-version = @man_pages_version@
> 
>  # Build tools.
>  CC = @CC@

Standard update to expose a new @subst@ as a make variable.

> --- a/configure
> +++ b/configure
...
> @@ -4091,11 +4095,11 @@ if test x$ac_prog_cxx_stdcxx = xno
>  then :
>    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CXX 
> option to enable C++11 features" >&5
>  printf %s "checking for $CXX option to enable C++11 features... " >&6; 
> }
> -if test ${ac_cv_prog_cxx_cxx11+y}
> +if test ${ac_cv_prog_cxx_11+y}
>  then :
...

This looks like you didn’t use the same version of Autoconf as the
last person to update configure.ac.  As I understand it we’re trying
to stick to a constant version.  Check with Joseph Myers for what you
should be using.

zw

Re: [patch v4] manual: add syscall list

[DJ Delorie]

"Zack Weinberg" <zack@owlfolio.org> writes:
>> +man_pages_version=6.8
>> +
>> +AC_ARG_WITH([man-pages],
>> +	    AS_HELP_STRING([--with-man-pages=VERSION],
>> +			   [tie manual to a specific man-pages version]),
>> +	    [man_pages_version=$withval],
>> +	    [])
>> +AC_SUBST(man_pages_version)
>> +
>>  AC_ARG_ENABLE([sanity-checks],
>>  	      AS_HELP_STRING([--disable-sanity-checks],
>>  			     [really do not use threads (should not be used except in 
>
> This is fine as is.  I might suggest a tiny change: instead of
> setting the default value for man_pages_version above the AC_ARG_WITH,
> set it in the action-if-not-given:

I started that way, but moved it out so it would be more obvious where
to change the value when the time comes.  This is the same thing we do
with the minimum kernel version, although in that case the default value
is spread across target-specific files.

> Also, I wonder if it makes sense to tie the default here to the
> default for --enable-kernel, assuming there is one.

--enable-kernel sets a minimum kernel version, whereas the man pages is
typically going to be the latest (maximum) version.

>> -if test ${ac_cv_prog_cxx_cxx11+y}
>> +if test ${ac_cv_prog_cxx_11+y}
>>  then :
> ...
>
> This looks like you didn’t use the same version of Autoconf as the
> last person to update configure.ac.  As I understand it we’re trying
> to stick to a constant version.  Check with Joseph Myers for what you
> should be using.

I used verison 2.71 (as noted in configure) right from the GNU ftp site.

The last time this line was changed, it was from
c6cb8783b5fb5896cb63fe9008b6a33351f3c777 which changed us from autoconf
2.69 to 2.71.

It turns out Fedora has added a patch to 2.71 that makes the '-' side of
the changes noted; which means that we can't use Fedora's autoconf if the
rule is (as documented) "GNU autoconf 2.71 (exactly)".

Or we need to change the rules.

  "If you change any of the 'configure.ac' files you will also need

     * GNU 'autoconf' 2.71 (exactly)"

Re: [patch v4] manual: add syscall list

[Zack Weinberg]

[cc list trimmed and Joseph added]

On Thu, May 23, 2024, at 3:38 PM, DJ Delorie wrote:
>> This is fine as is.  I might suggest a tiny change: instead of
>> setting the default value for man_pages_version above the AC_ARG_WITH,
>> set it in the action-if-not-given:
>
> I started that way, but moved it out so it would be more obvious where
> to change the value when the time comes.  This is the same thing we do
> with the minimum kernel version, although in that case the default value
> is spread across target-specific files.

OK, if we're doing the same thing elsewhere then it's good to be consistent.

> --enable-kernel sets a minimum kernel version, whereas the man pages is
> typically going to be the latest (maximum) version.

I see.

>> This looks like you didn’t use the same version of Autoconf as the
>> last person to update configure.ac.  As I understand it we’re trying
>> to stick to a constant version.  Check with Joseph Myers for what you
>> should be using.
>
> I used verison 2.71 (as noted in configure) right from the GNU ftp site.
>
> The last time this line was changed, it was from
> c6cb8783b5fb5896cb63fe9008b6a33351f3c777 which changed us from autoconf
> 2.69 to 2.71.
>
> It turns out Fedora has added a patch to 2.71 that makes the '-' side of
> the changes noted; which means that we can't use Fedora's autoconf if the
> rule is (as documented) "GNU autoconf 2.71 (exactly)".
>
> Or we need to change the rules.

I have no opinion here.  Joseph, do you have an opinion?

zw

Re: [patch v4] manual: add syscall list

[DJ Delorie]

"Zack Weinberg" <zack@owlfolio.org> writes:
> I have no opinion here.  Joseph, do you have an opinion?

For completeness, here's the Fedora patch...

+From f460883035ef849a2248b1713f711292ec19f4f0 Mon Sep 17 00:00:00 2001
+From: Emanuele Giaquinta <emanuele.giaquinta@gmail.com>
+Date: Fri, 14 May 2021 09:06:20 +0300
+Subject: [PATCH] _AC_PROG_CXX_STDCXX_EDITION_TRY: fix typo in variable name
+
+The typo causes "ac_prog_cxx_stdcxx" to be always set to "cxx11",
+regardless of whether the C++ compiler supports C++11.
+Message-Id: <YJ4TXAeJcvU0oSec@FSAPPLE2215.fi.f-secure.com>
+(tiny change)
+---
+ lib/autoconf/c.m4 | 4 ++--
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+
+diff --git a/lib/autoconf/c.m4 b/lib/autoconf/c.m4
+index 9f881f0b..47434c89 100644
+--- a/lib/autoconf/c.m4
++++ b/lib/autoconf/c.m4
+@@ -2749,8 +2749,8 @@ AC_DEFUN([_AC_PROG_CXX_STDCXX_EDITION_TRY],
+ [AC_REQUIRE([_AC_CXX_CXX$1_TEST_PROGRAM])]dnl
+ [AS_IF([test x$ac_prog_cxx_stdcxx = xno],
+ [AC_MSG_CHECKING([for $CXX option to enable C++$1 features])
+-AC_CACHE_VAL(ac_cv_prog_cxx_$1,
+-[ac_cv_prog_cxx_$1=no
++AC_CACHE_VAL(ac_cv_prog_cxx_cxx$1,
++[ac_cv_prog_cxx_cxx$1=no
+ ac_save_CXX=$CXX
+ AC_LANG_CONFTEST([AC_LANG_DEFINES_PROVIDED][$][ac_cxx_conftest_cxx$1_program])
+ for ac_arg in '' m4_normalize(m4_defn([_AC_CXX_CXX$1_OPTIONS]))
+-- 
+2.37.2
+

Re: [patch v4] manual: add syscall list

[Joseph Myers]

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

On Thu, 23 May 2024, Zack Weinberg wrote:

> >> This looks like you didn’t use the same version of Autoconf as the
> >> last person to update configure.ac.  As I understand it we’re trying
> >> to stick to a constant version.  Check with Joseph Myers for what you
> >> should be using.
> >
> > I used verison 2.71 (as noted in configure) right from the GNU ftp site.
> >
> > The last time this line was changed, it was from
> > c6cb8783b5fb5896cb63fe9008b6a33351f3c777 which changed us from autoconf
> > 2.69 to 2.71.
> >
> > It turns out Fedora has added a patch to 2.71 that makes the '-' side of
> > the changes noted; which means that we can't use Fedora's autoconf if the
> > rule is (as documented) "GNU autoconf 2.71 (exactly)".
> >
> > Or we need to change the rules.
> 
> I have no opinion here.  Joseph, do you have an opinion?

We should be using the unmodified upstream version to generate the 
checked-in files.

-- 
Joseph S. Myers
josmyers@redhat.com

Re: [patch v4] manual: add syscall list

[Alejandro Colomar]

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

Hi Zack,

On Thu, May 23, 2024 at 12:59:13PM GMT, Zack Weinberg wrote:
> On Wed, May 22, 2024, at 3:41 PM, DJ Delorie wrote:
> > [v4 cleans up comment text and list prefixes]
> 
> I saw something go by earlier about previous reviewers not being
> confident in their understanding of the changes to the configure.ac,
> so let me jump in and review that part...

That was me.  :)

> >  AC_DEFINE_UNQUOTED(TIMEOUTFACTOR, $timeoutfactor)
> > 
> > +AC_ARG_WITH([man-pages],
> > +	    AS_HELP_STRING([--with-man-pages=VERSION],
> > +			   [tie manual to a specific man-pages version]),
> > +	    [man_pages_version=$withval],
> > +	    [man_pages_version=6.8])
> > +AC_SUBST(man_pages_version)
> 
> Also, I wonder if it makes sense to tie the default here to the
> default for --enable-kernel, assuming there is one.

The versions of the Linux man-pages project are independent of the Linux
kernel ones.  In fact, I think all of my releases will be 6.x, and 7.x
will be for whoever is the maintainer after me.

Have a lovely night!
Alex

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

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