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

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

[Alejandro Colomar]

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.

......

$ syscall='getcpu';
$ ret='int';
$ find glibc/ -type f -name '*.h' \
  |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
glibc/sysdeps/unix/sysv/linux/bits/sched.h:92:
extern int getcpu (unsigned int *, unsigned int *) __THROW;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getcpu.2 | 55 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 30 insertions(+), 25 deletions(-)

diff --git a/man2/getcpu.2 b/man2/getcpu.2
index 46e4d53ff..a9588119b 100644
--- a/man2/getcpu.2
+++ b/man2/getcpu.2
@@ -16,8 +16,7 @@ getcpu \- determine CPU and NUMA node on which the calling thread is running
 .nf
 .B #include <linux/getcpu.h>
 .PP
-.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node ,
-.BI "           struct getcpu_cache *" tcache );
+.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node );
 .fi
 .SH DESCRIPTION
 The
@@ -36,10 +35,10 @@ When either
 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 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
@@ -71,6 +70,12 @@ Library support was added in glibc 2.29
 (Earlier glibc versions did not provide a wrapper for this system call,
 necessitating the use of
 .BR syscall (2).)
+.PP
+The Linux system call has a third argument
+.IR tcache ,
+which since kernel 2.6.24 is ignored.
+It should be specified as NULL.
+The glibc wrapper hides that parameter.
 .SH CONFORMING TO
 .BR getcpu ()
 is Linux-specific.
@@ -82,25 +87,25 @@ The intention of
 .BR getcpu ()
 is to allow programs to make optimizations with per-CPU data
 or for NUMA optimization.
-.PP
-The
-.I tcache
-argument is unused since Linux 2.6.24.
-.\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1
-.\" Author: Ingo Molnar <mingo@elte.hu>
-.\" 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,
-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 ().
-Use of the cache could speed
-.BR getcpu ()
-calls, at the cost that there was a very small chance that
-the returned information would be out of date.
-The caching mechanism was considered to cause problems when
-migrating threads between CPUs, and so the argument is now ignored.
+.\" .PP
+.\" The
+.\" .I tcache
+.\" argument is unused since Linux 2.6.24.
+.\" .\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1
+.\" .\" Author: Ingo Molnar <mingo@elte.hu>
+.\" .\" 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,
+.\" 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 ().
+.\" Use of the cache could speed
+.\" .BR getcpu ()
+.\" calls, at the cost that there was a very small chance that
+.\" the returned information would be out of date.
+.\" The caching mechanism was considered to cause problems when
+.\" migrating threads between CPUs, and so the argument is now ignored.
 .\"
 .\" ===== Before kernel 2.6.24: =====
 .\" .I tcache
-- 
2.29.2

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

[Michael Kerrisk (man-pages)]

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.

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@elte.hu>
 .\" 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 ().

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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@elte.hu>
>  .\" 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/