| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| getcpu \- determine CPU and NUMA node on which the calling thread is running |
| .SH SYNOPSIS |
| .nf |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <sched.h> |
| .PP |
| .BI "int getcpu(unsigned int *" cpu ", unsigned int *" 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. |
| .PP |
| 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 VERSIONS |
| .BR getcpu () |
| 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. |
| .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. |
| .\" |
| .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, |
| 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 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 kernel 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 kernel 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 SEE ALSO |
| .BR mbind (2), |
| .BR sched_setaffinity (2), |
| .BR set_mempolicy (2), |
| .BR sched_getcpu (3), |
| .BR cpuset (7), |
| .BR vdso (7) |