Start of man-pages-5.03: renaming .Announce and .lsm files

[thirdparty/man-pages.git] / man2 / getcpu.2

diff --git a/man2/getcpu.2 b/man2/getcpu.2
index 4168f54bba6c4abb8af9f936ddc268fc760de0d7..fc36b43b50e1bfbced7f29ec0b94aa371ef78687 100644 (file)
--- a/man2/getcpu.2
+++ b/man2/getcpu.2
@@ -1,16 +1,21 @@
 .\" This man page is Copyright (C) 2006 Andi Kleen <ak@muc.de>.
+.\"
+.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
 .\" Permission is granted to distribute possibly modified copies
 .\" of this page provided the header is included verbatim,
 .\" and in case of nontrivial modification author and date
 .\" of the modification is added to the header.
+.\" %%%LICENSE_END
+.\"
 .\" 2008, mtk, various edits
-.TH GETCPU 2 2012-05-09 "Linux" "Linux Programmer's Manual"
+.\"
+.TH GETCPU 2 2019-03-06 "Linux" "Linux Programmer's Manual"
 .SH NAME
 getcpu \- determine CPU and NUMA node on which the calling thread is running
 .SH SYNOPSIS
 .nf
 .B #include <linux/getcpu.h>
-.sp
+.PP
 .BI "int getcpu(unsigned *" cpu ", unsigned *" node \
 ", struct getcpu_cache *" tcache );
 .fi
@@ -31,12 +36,14 @@ When either
 or
 .I node
 is NULL nothing is written to the respective pointer.
-
-The third argument to this system call is nowadays unused (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
-is only guaranteed to be current at the time of the call:
+is guaranteed to be current only at the time of the call:
 unless the CPU affinity has been fixed using
 .BR sched_setaffinity (2),
 the kernel might change the CPU at any time.
@@ -48,7 +55,7 @@ The caller must allow for the possibility that the information returned in
 and
 .I node
 is no longer current by the time the call returns.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 On success, 0 is returned.
 On error, \-1 is returned, and
 .I errno
@@ -59,23 +66,23 @@ is set appropriately.
 Arguments point outside the calling process's address space.
 .SH VERSIONS
 .BR getcpu ()
-was added in kernel 2.6.19 for x86_64 and i386.
+was added in kernel 2.6.19 for x86-64 and i386.
+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).)
 .SH CONFORMING TO
 .BR getcpu ()
-is Linux specific.
+is Linux-specific.
 .SH NOTES
-Linux makes a best effort to make this call as fast possible.
+Linux makes a best effort to make this call as fast as possible.
+(On some architectures, this is done via an implementation in the
+.BR vdso (7).)
 The intention of
 .BR getcpu ()
 is to allow programs to make optimizations with per-CPU data
 or for NUMA optimization.
-
-Glibc does not provide a wrapper for this system call; call it using
-.BR syscall (2);
-or use
-.BR sched_getcpu (3)
-instead.
-
+.PP
 The
 .I tcache
 argument is unused since Linux 2.6.24.
@@ -120,7 +127,7 @@ migrating threads between CPUs, and so the argument is now ignored.
 .\" With a cache
 .\" .BR getcpu ()
 .\" is faster.
-.\" However, the cached information is only updated once per jiffy (see
+.\" However, the cached information is updated only once per jiffy (see
 .\" .BR time (7)).
 .\" This means that the information could theoretically be out of date,
 .\" although in practice the scheduler's attempt to maintain
@@ -131,4 +138,5 @@ migrating threads between CPUs, and so the argument is now ignored.
 .BR sched_setaffinity (2),
 .BR set_mempolicy (2),
 .BR sched_getcpu (3),
-.BR cpuset (7)
+.BR cpuset (7),
+.BR vdso (7)