[patch v4] manual: add syscall list

[Alejandro Colomar]

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/>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20240523/4a92a527/attachment.sig>