summaryrefslogtreecommitdiffstats
path: root/man7/vdso.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/vdso.7')
-rw-r--r--man7/vdso.750
1 files changed, 25 insertions, 25 deletions
diff --git a/man7/vdso.7 b/man7/vdso.7
index 338ef72..d37360c 100644
--- a/man7/vdso.7
+++ b/man7/vdso.7
@@ -11,13 +11,13 @@
.\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken
.\" http://www.trilithium.com/johan/2005/08/linux-gate/
.\"
-.TH vDSO 7 2023-05-03 "Linux man-pages 6.05.01"
+.TH vDSO 7 2024-02-18 "Linux man-pages 6.7"
.SH NAME
vdso \- overview of the virtual ELF dynamic shared object
.SH SYNOPSIS
.nf
.B #include <sys/auxv.h>
-.PP
+.P
.B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR);
.fi
.SH DESCRIPTION
@@ -29,7 +29,7 @@ as the vDSO is most commonly called by the C library.
This way you can code in the normal way using standard functions
and the C library will take care
of using any functionality that is available via the vDSO.
-.PP
+.P
Why does the vDSO exist at all?
There are some system calls the kernel provides that
user-space code ends up using frequently,
@@ -37,7 +37,7 @@ to the point that such calls can dominate overall performance.
This is due both to the frequency of the call as well as the
context-switch overhead that results
from exiting user space and entering the kernel.
-.PP
+.P
The rest of this documentation is geared toward the curious and/or
C library writers rather than general developers.
If you're trying to call the vDSO in your own application rather than using
@@ -56,14 +56,14 @@ Rather than require the C library to figure out if this functionality is
available at run time,
the C library can use functions provided by the kernel in
the vDSO.
-.PP
+.P
Note that the terminology can be confusing.
On x86 systems, the vDSO function
used to determine the preferred method of making a system call is
named "__kernel_vsyscall", but on x86-64,
the term "vsyscall" also refers to an obsolete way to ask the kernel
what time it is or what CPU the caller is on.
-.PP
+.P
One frequently used system call is
.BR gettimeofday (2).
This system call is called both directly by user-space applications
@@ -86,7 +86,7 @@ each program in the initial auxiliary vector (see
via the
.B AT_SYSINFO_EHDR
tag.
-.PP
+.P
You must not assume the vDSO is mapped at any particular location in the
user's memory map.
The base address will usually be randomized at run time every time a new
@@ -95,7 +95,7 @@ process image is created (at
time).
This is done for security reasons,
to prevent "return-to-libc" attacks.
-.PP
+.P
For some architectures, there is also an
.B AT_SYSINFO
tag.
@@ -111,7 +111,7 @@ and allows the C library to detect available functionality at
run time when running under different kernel versions.
Oftentimes the C library will do detection with the first call and then
cache the result for subsequent calls.
-.PP
+.P
All symbols are also versioned (using the GNU version format).
This allows the kernel to update the function signature without breaking
backward compatibility.
@@ -120,12 +120,12 @@ return value.
Thus, when looking up a symbol in the vDSO,
you must always include the version
to match the ABI you expect.
-.PP
+.P
Typically the vDSO follows the naming convention of prefixing
all symbols with "__vdso_" or "__kernel_"
so as to distinguish them from other standard symbols.
For example, the "gettimeofday" function is named "__vdso_gettimeofday".
-.PP
+.P
You use the standard C calling conventions when calling
any of these functions.
No need to worry about weird register or stack behavior.
@@ -134,7 +134,7 @@ No need to worry about weird register or stack behavior.
When you compile the kernel,
it will automatically compile and link the vDSO code for you.
You will frequently find it under the architecture-specific directory:
-.PP
+.P
.in +4n
.EX
find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq]
@@ -173,7 +173,7 @@ x86/x32 linux\-vdso.so.1
.ft P
\}
.SS strace(1), seccomp(2), and the vDSO
-When tracing systems calls with
+When tracing system calls with
.BR strace (1),
symbols (system calls) that are exported by the vDSO will
.I not
@@ -184,7 +184,7 @@ filters.
.SH ARCHITECTURE-SPECIFIC NOTES
The subsections below provide architecture-specific notes
on the vDSO.
-.PP
+.P
Note that the vDSO that is used is based on the ABI of your user-space code
and not the ABI of the kernel.
Thus, for example,
@@ -211,14 +211,14 @@ __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1)
.in
.ft P
\}
-.PP
+.P
.\" See linux/arch/arm/kernel/entry-armv.S
.\" See linux/Documentation/arm/kernel_user_helpers.rst
Additionally, the ARM port has a code page full of utility functions.
Since it's just a raw page of code, there is no ELF information for doing
symbol lookups or versioning.
It does provide support for different versions though.
-.PP
+.P
For information on this code page,
it's best to refer to the kernel documentation
as it's extremely detailed and covers everything you need to know:
@@ -254,7 +254,7 @@ There is no provision for backward compatibility
beyond sniffing raw opcodes,
but as this is an embedded CPU, it can get away with things\[em]some of the
object formats it runs aren't even ELF based (they're bFLT/FLAT).
-.PP
+.P
For information on this code page,
it's best to refer to the public documentation:
.br
@@ -295,7 +295,7 @@ __kernel_syscall_via_epc LINUX_2.5
.in
.ft P
\}
-.PP
+.P
The Itanium port is somewhat tricky.
In addition to the vDSO above, it also has "light-weight system calls"
(also known as "fast syscalls" or "fsys").
@@ -337,12 +337,12 @@ the page to the process via the SR2 register.
The permissions on the page are such that merely executing those addresses
automatically executes with kernel privileges and not in user space.
This is done to match the way HP-UX works.
-.PP
+.P
Since it's just a raw page of code, there is no ELF information for doing
symbol lookups or versioning.
Simply call into the appropriate offset via the branch instruction,
for example:
-.PP
+.P
.in +4n
.EX
ble <offset>(%sr2, %r0)
@@ -394,7 +394,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15
.in
.ft P
\}
-.PP
+.P
Before Linux 5.6,
.\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39
the
@@ -434,7 +434,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15
.in
.ft P
\}
-.PP
+.P
Before Linux 4.16,
.\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1
the
@@ -598,15 +598,15 @@ to user space, so it was reconceived as a vDSO in the current format.
.BR syscalls (2),
.BR getauxval (3),
.BR proc (5)
-.PP
+.P
The documents, examples, and source code in the Linux source code tree:
-.PP
+.P
.in +4n
.EX
Documentation/ABI/stable/vdso
Documentation/ia64/fsys.rst
Documentation/vDSO/* (includes examples of using the vDSO)
-.PP
+.P
find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq]
.EE
.in