lkml.org 
[lkml]   [2021]   [Jan]   [2]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    SubjectRe: [PATCH] getcpu.2: Document glibc wrapper instead of kernel syscall
    From
    Date


    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/

    \
     
     \ /
      Last update: 2021-01-02 18:25    [W:2.296 / U:0.036 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site