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

From: Alejandro Colomar <alx.manpages@gmail.com>
To: mtk.manpages@gmail.com
Cc: Alejandro Colomar <alx.manpages@gmail.com>,
	linux-man@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH] getcpu.2: Document glibc wrapper instead of kernel syscall
Date: Wed, 30 Dec 2020 22:41:46 +0100	[thread overview]
Message-ID: <20201230214147.874671-6-alx.manpages@gmail.com> (raw)

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

