Re: [PATCH] getcpu.2: Document glibc wrapper instead of kernel syscall

[Alejandro Colomar (man-pages)]

On 1/2/21 9:41 AM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 12/30/20 10:41 PM, Alejandro Colomar wrote:
>> The glibc wrapper doesn't provide the third argument.
>> Simplify the info about the (unused) kernel parameter
>> to the minimum that is useful.
>>
>> kernels <=2.6.23 are EOL since a long time ago.
>>
>> The old info is commented out instead of removed.
> 
> I tend to be rather conservative about preserving historical
> detail in the manual pages. Yes, 2.6.23 may be EOL from the
> kernel community's point of view, but even in quite recent
> times I've run into folk in the embedded world that who have
> to at the very least support 2.6.* systems. So, as a general
> principle, I'm inclined to retain the kind of info that this
> patch removes. (I admit though that this is an extreme case:
> historical behavior in a system call that is not frequently
> used.)
> 
> There are exceptions. Occassionaly I run into historical 
> info in manual pages that is clearly wrong, or incomplete.
> In such cases, I am sometimes inclined to trim the details,
> rather than invest the effort in working out all of the
> historical details.
> 
> Clearly though, some fix is needed, since we now have 
> a glibc wrapper that has just two arguments. I've applied
> the patch below.

Hi Michael,

Agreed :-)

Cheers,

Alex

> 
> Cheers,
> 
> Michael
> 
> diff --git a/man2/getcpu.2 b/man2/getcpu.2
> index a75123f97..59089bd74 100644
> --- a/man2/getcpu.2
> +++ b/man2/getcpu.2
> @@ -14,10 +14,10 @@
>  getcpu \- determine CPU and NUMA node on which the calling thread is running
>  .SH SYNOPSIS
>  .nf
> -.B #include <linux/getcpu.h>
> +.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
> +.B #include <sched.h>
>  .PP
> -.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node \
> -", struct getcpu_cache *" tcache );
> +.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node );
>  .fi
>  .SH DESCRIPTION
>  The
> @@ -37,10 +37,6 @@ or
>  .I node
>  is NULL nothing is written to the respective pointer.
>  .PP
> -The third argument to this system call is nowadays unused,
> -and should be specified as NULL
> -unless portability to Linux 2.6.23 or earlier is required (see NOTES).
> -.PP
>  The information placed in
>  .I cpu
>  is guaranteed to be current only at the time of the call:
> @@ -82,16 +78,31 @@ The intention of
>  .BR getcpu ()
>  is to allow programs to make optimizations with per-CPU data
>  or for NUMA optimization.
> +.\"
> +.SS C library/kernel differences
> +The kernel system call has a third argument:
> +.PP
> +.in +4n
> +.nf
> +.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node ,
> +.BI "           struct getcpu_cache *" tcache );
> +.fi
> +.in
>  .PP
>  The
>  .I tcache
> -argument is unused since Linux 2.6.24.
> +argument is unused since Linux 2.6.24,
> +and (when invoking the system call directly)
> +should be specified as NULL,
> +unless portability to Linux 2.6.23 or earlier is required.
> +.PP
>  .\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1
>  .\" Author: Ingo Molnar <mingo@xxxxxxx>
>  .\" Date:   Wed Nov 7 18:37:48 2007 +0100
>  .\" x86: ignore the sys_getcpu() tcache parameter
> -In earlier kernels,
> -if this argument was non-NULL,
> +In Linux 2.6.23 and earlier, if the
> +.I tcache
> +argument was non-NULL,
>  then it specified a pointer to a caller-allocated buffer in thread-local
>  storage that was used to provide a caching mechanism for
>  .BR getcpu ().
> 

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