[PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's

[Alejandro Colomar (man-pages)]

Hi Florian,

On 4/12/21 8:17 AM, Florian Weimer wrote:
> * Michael Kerrisk via Libc-alpha:
> 
>> So, I think I'm okay with the syscall() changes in the SYNOPSIS.
>> It might just take me a moment to get used to them. However, I do
>> wonder if it is worth retaining a comment in the SYSNOPSIS,
>> something like:
>>
>>     SYNOPSIS
>>         #include <asm/prctl.h>        /* Definition of ARCH_* constants */
>>         #include <sys/syscall.h>      /* Definition of SYS_* constants */
>>         #include <unistd.h>
>>
>>         int syscall(SYS_arch_prctl, int code, unsigned long addr);
>>         int syscall(SYS_arch_prctl, int code, unsigned long *addr);
>>
>>         Note: glibc provides no wrapper for arch_prctl(), necessitating
>>         the use of syscall(2).
>>
>> Without something like this, the reader may be puzzled at the use of
>> syscall().
>>
>> What do you think?
> 
> Would it be possible to use real C syntax?
> 
>    int code;
>    unsigned long addr;
>    int result;
>    result = syscall (SYS_arch_prctl, code, addr);
>    result = syscall (SYS_arch_prctl, code, &addr);

I think that adds too many lines, and doesn't add much value.  Yes, it 
provides pure C syntax, which might be a bit easier to understand, but 
is it worth it?

I followed the syntax already used by some manual pages such as the 
ioctl_*(2) pages (see ioctl_fat(2) for example), although I must admit 
it was a bit rare the first time I saw it; but I think it's a good 
compromise between being short and providing information.

I think the EXAMPLES section can better clarify how to use the function 
if there're any doubts.

> 
> Or perhaps omit the result variable:
> 
>    int code;
>    unsigned long addr;
>    syscall (SYS_arch_prctl, code, addr);

That wouldn't provide the reader with the info about which type should 
he expect as return; the most important part being the signedness of the 
type.

On 4/12/21 8:39 AM, Jakub Wilk wrote:
 >>
 >
 > Or, more succinctly, put the types in comments:
 >
 >    syscall(SYS_arch_prctl, /* int */ code, /* unsigned long */ addr);

I'm not sure.  I see the point in doing this, but I think I prefer my 
version, because it has less noise.  But I might be a bit biased :)


Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/