[PATCH v2] manual: describe syscall numbers not supported via syscall()

[Adhemerval Zanella Netto]

On 16/09/25 06:00, Yury Khrustalev wrote:
> The syscall() function allows to make system calls directly, however,
> in the case of system calls that affect internal state of process or
> thread, the caller would have to take care of extensive setup necessary
> for the internals of Glibc to work correctly in the child threads. This
> may make using syscall() with these syscall numbers impractical and
> prone to undefined behaviour.
> 
> ---
> 
> This need for this patch was discussed in
> https://patchwork.sourceware.org/project/glibc/patch/20250901095112.1672473-3-yury.khrustalev@arm.com/
> 
> v1: https://patchwork.sourceware.org/project/glibc/list/?series=51954
> 
> base-commit: 13d67746cb

LGTM, thanks.

> 
> ---
> 
>  manual/startup.texi | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/manual/startup.texi b/manual/startup.texi
> index 9545fcc526..11fe58c5a6 100644
> --- a/manual/startup.texi
> +++ b/manual/startup.texi
> @@ -737,6 +737,12 @@ anyway.
>  @code{syscall} does not provide cancellation logic, even if the system
>  call you're calling is listed as cancellable above.
>  
> +Using @code{syscall} with system calls that affect the internal state of
> +process of thread will likely result in undefined behavior. For this reason,
> +at least the following system call numbers are not supported when invoked via
> +@code{syscall}: @code{SYS_clone}, @code{SYS_clone2}, @code{SYS_clone3},
> +@code{SYS_rt_sigreturn}, @code{SYS_sigreturn}, @code{SYS_vfork}.

Some ABIs also support __NR_fork, but I am not sure if it is worth to mention
here.

> +
>  @code{syscall} is declared in @file{unistd.h}.
>  
>  @deftypefun {long int} syscall (long int @var{sysno}, @dots{})
> @@ -804,7 +810,6 @@ if (rc == -1)
>  
>  @end deftypefun
>  
> -
>  @node Program Termination
>  @section Program Termination
>  @cindex program termination