Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 147 insertions, 0 deletions

diff --git a/man/man2/getcpu.2 b/man/man2/getcpu.2
new file mode 100644
index 0000000..f2097f9
--- /dev/null
+++ b/man/man2/getcpu.2
@@ -0,0 +1,147 @@
+.\" SPDX-License-Identifier: Linux-man-pages-1-para
+.\"
+.\" This man page is Copyright (C) 2006 Andi Kleen <ak@muc.de>.
+.\"
+.\" 2008, mtk, various edits
+.\"
+.TH getcpu 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getcpu \- determine CPU and NUMA node on which the calling thread is running
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
+.B #include <sched.h>
+.P
+.BI "int getcpu(unsigned int *_Nullable " cpu ", \
+unsigned int *_Nullable " node );
+.fi
+.SH DESCRIPTION
+The
+.BR getcpu ()
+system call identifies the processor and node on which the calling
+thread or process is currently running and writes them into the
+integers pointed to by the
+.I cpu
+and
+.I node
+arguments.
+The processor is a unique small integer identifying a CPU.
+The node is a unique small identifier identifying a NUMA node.
+When either
+.I cpu
+or
+.I node
+is NULL nothing is written to the respective pointer.
+.P
+The information placed in
+.I cpu
+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.
+(Normally this does not happen
+because the scheduler tries to minimize movements between CPUs to
+keep caches hot, but it is possible.)
+The caller must allow for the possibility that the information returned in
+.I cpu
+and
+.I node
+is no longer current by the time the call returns.
+.SH RETURN VALUE
+On success, 0 is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+Arguments point outside the calling process's address space.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.19 (x86-64 and i386),
+glibc 2.29.
+.\"
+.SS C library/kernel differences
+The kernel system call has a third argument:
+.P
+.in +4n
+.nf
+.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node ,
+.BI "           struct getcpu_cache *" tcache );
+.fi
+.in
+.P
+The
+.I tcache
+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.
+.P
+.\" 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 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 ().
+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 Linux 2.6.24: =====
+.\" .I tcache
+.\" is a pointer to a
+.\" .IR "struct getcpu_cache"
+.\" that is used as a cache by
+.\" .BR getcpu ().
+.\" The caller should put the cache into a thread-local variable
+.\" if the process is multithreaded,
+.\" because the cache cannot be shared between different threads.
+.\" .I tcache
+.\" can be NULL.
+.\" If it is not NULL
+.\" .BR getcpu ()
+.\" will use it to speed up operation.
+.\" The information inside the cache is private to the system call
+.\" and should not be accessed by the user program.
+.\" The information placed in the cache can change between Linux releases.
+.\"
+.\" When no cache is specified
+.\" .BR getcpu ()
+.\" will be slower,
+.\" but always retrieve the current CPU and node information.
+.\" With a cache
+.\" .BR getcpu ()
+.\" is faster.
+.\" 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
+.\" soft CPU affinity means that the information is unlikely to change
+.\" over the course of the caching interval.
+.SH NOTES
+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.
+.SH SEE ALSO
+.BR mbind (2),
+.BR sched_setaffinity (2),
+.BR set_mempolicy (2),
+.BR sched_getcpu (3),
+.BR cpuset (7),
+.BR vdso (7)