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/
