Debian Codegraph @

upstream/debian-unstable/man7/vdso.7

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
5 .\" This page is in the public domain.
6 .\" %%%LICENSE_END
7 .\"
8 .TH vDSO 7 2025-12-25 "Linux man-pages 6.18"
9 .SH NAME
10 vdso \- overview of the virtual ELF dynamic shared object
11 .SH SYNOPSIS
12 .nf
13 .B #include <sys/auxv.h>
14 .P
15 .B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR);
16 .fi
17 .SH DESCRIPTION
18 The "vDSO" (virtual dynamic shared object) is a small shared library that
19 the kernel automatically maps into the
20 address space of all user-space applications.
21 Applications usually do not need to concern themselves with these details
22 as the vDSO is most commonly called by the C library.
23 This way you can code in the normal way using standard functions
24 and the C library will take care
25 of using any functionality that is available via the vDSO.
26 .P
27 Why does the vDSO exist at all?
28 There are some system calls the kernel provides that
29 user-space code ends up using frequently,
30 to the point that such calls can dominate overall performance.
31 This is due both to the frequency of the call as well as the
32 context-switch overhead that results
33 from exiting user space and entering the kernel.
34 .P
35 The rest of this documentation is geared toward the curious and/or
36 C library writers rather than general developers.
37 If you're trying to call the vDSO in your own application rather than using
38 the C library, you're most likely doing it wrong.
39 .SS Example background
40 Making system calls can be slow.
41 In x86 32-bit systems, you can trigger a software interrupt
42 .RI ( "int $0x80" )
43 to tell the kernel you wish to make a system call.
44 However, this instruction is expensive: it goes through
45 the full interrupt-handling paths
46 in the processor's microcode as well as in the kernel.
47 Newer processors have faster (but backward incompatible) instructions to
48 initiate system calls.
49 Rather than require the C library to figure out if this functionality is
50 available at run time,
51 the C library can use functions provided by the kernel in
52 the vDSO.
53 .P
54 Note that the terminology can be confusing.
55 On x86 systems, the vDSO function
56 used to determine the preferred method of making a system call is
57 named "__kernel_vsyscall", but on x86-64,
58 the term "vsyscall" also refers to an obsolete way to ask the kernel
59 what time it is or what CPU the caller is on.
60 .P
61 One frequently used system call is
62 .BR gettimeofday (2).
63 This system call is called both directly by user-space applications
64 as well as indirectly by
65 the C library.
66 Think timestamps or timing loops or polling\[em]all of these
67 frequently need to know what time it is right now.
68 This information is also not secret\[em]any application in any
69 privilege mode (root or any unprivileged user) will get the same answer.
70 Thus the kernel arranges for the information required to answer
71 this question to be placed in memory the process can access.
72 Now a call to
73 .BR gettimeofday (2)
74 changes from a system call to a normal function
75 call and a few memory accesses.
76 .SS Finding the vDSO
77 The base address of the vDSO (if one exists) is passed by the kernel to
78 each program in the initial auxiliary vector (see
79 .BR getauxval (3)),
80 via the
81 .B AT_SYSINFO_EHDR
82 tag.
83 .P
84 You must not assume the vDSO is mapped at any particular location in the
85 user's memory map.
86 The base address will usually be randomized at run time every time a new
87 process image is created (at
88 .BR execve (2)
89 time).
90 This is done for security reasons,
91 to prevent "return-to-libc" attacks.
92 .P
93 For some architectures, there is also an
94 .B AT_SYSINFO
95 tag.
96 This is used only for locating the vsyscall entry point and is frequently
97 omitted or set to 0 (meaning it's not available).
98 This tag is a throwback to the initial vDSO work (see
99 .I History
100 below) and its use should be avoided.
101 .SS File format
102 Since the vDSO is a fully formed ELF image, you can do symbol lookups on it.
103 This allows new symbols to be added with newer kernel releases,
104 and allows the C library to detect available functionality at
105 run time when running under different kernel versions.
106 Oftentimes the C library will do detection with the first call and then
107 cache the result for subsequent calls.
108 .P
109 All symbols are also versioned (using the GNU version format).
110 This allows the kernel to update the function signature without breaking
111 backward compatibility.
112 This means changing the arguments that the function accepts as well as the
113 return value.
114 Thus, when looking up a symbol in the vDSO,
115 you must always include the version
116 to match the ABI you expect.
117 .P
118 Typically the vDSO follows the naming convention of prefixing
119 all symbols with "__vdso_" or "__kernel_"
120 so as to distinguish them from other standard symbols.
121 For example, the "gettimeofday" function is named "__vdso_gettimeofday".
122 .P
123 You use the standard C calling conventions when calling
124 any of these functions.
125 No need to worry about weird register or stack behavior.
126 .SH NOTES
127 .SS Source
128 When you compile the kernel,
129 it will automatically compile and link the vDSO code for you.
130 You will frequently find it under the architecture-specific directory:
131 .P
132 .in +4n
133 .EX
134 find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq]
135 .EE
136 .in
137 .\"
138 .SS vDSO names
139 The name of the vDSO varies across architectures.
140 It will often show up in things like glibc's
141 .BR ldd (1)
142 output.
143 The exact name should not matter to any code, so do not hardcode it.
144 .P
145 .TS
146 lB lB
147 l l .
148 user ABI vDSO name
149 _
150 aarch64 linux\-vdso.so.1
151 arm linux\-vdso.so.1
152 ia64 linux\-gate.so.1
153 mips linux\-vdso.so.1
154 ppc/32 linux\-vdso32.so.1
155 ppc/64 linux\-vdso64.so.1
156 riscv linux\-vdso.so.1
157 s390 linux\-vdso32.so.1
158 s390x linux\-vdso64.so.1
159 sh linux\-gate.so.1
160 i386 linux\-gate.so.1
161 x86-64 linux\-vdso.so.1
162 x86/x32 linux\-vdso.so.1
163 .TE
164 .SS strace(1), seccomp(2), and the vDSO
165 When tracing system calls with
166 .BR strace (1),
167 symbols (system calls) that are exported by the vDSO will
168 .I not
169 appear in the trace output.
170 Those system calls will likewise not be visible to
171 .BR seccomp (2)
172 filters.
173 .SH ARCHITECTURE-SPECIFIC NOTES
174 The subsections below provide architecture-specific notes
175 on the vDSO.
176 .P
177 Note that the vDSO that is used is based on the ABI of your user-space code
178 and not the ABI of the kernel.
179 Thus, for example,
180 when you run an i386 32-bit ELF binary,
181 you'll get the same vDSO regardless of whether you run it under
182 an i386 32-bit kernel or under an x86-64 64-bit kernel.
183 Therefore, the name of the user-space ABI should be used to determine
184 which of the sections below is relevant.
185 .SS ARM functions
186 .\" See linux/arch/arm/vdso/vdso.lds.S
187 .\" Commit: 8512287a8165592466cb9cb347ba94892e9c56a5
188 The table below lists the symbols exported by the vDSO.
189 .P
190 .TS
191 lB lB
192 l l .
193 symbol version
194 _
195 __vdso_gettimeofday LINUX_2.6 (exported since Linux 4.1)
196 __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1)
197 .TE
198 .P
199 .\" See linux/arch/arm/kernel/entry-armv.S
200 .\" See linux/Documentation/arm/kernel_user_helpers.rst
201 Additionally, the ARM port has a code page full of utility functions.
202 Since it's just a raw page of code, there is no ELF information for doing
203 symbol lookups or versioning.
204 It does provide support for different versions though.
205 .P
206 For information on this code page,
207 it's best to refer to the kernel documentation
208 as it's extremely detailed and covers everything you need to know:
209 .IR Documentation/arm/kernel_user_helpers.rst .
210 .SS aarch64 functions
211 .\" See linux/arch/arm64/kernel/vdso/vdso.lds.S
212 The table below lists the symbols exported by the vDSO.
213 .P
214 .TS
215 lB lB
216 l l .
217 symbol version
218 _
219 __kernel_rt_sigreturn LINUX_2.6.39
220 __kernel_gettimeofday LINUX_2.6.39
221 __kernel_clock_gettime LINUX_2.6.39
222 __kernel_clock_getres LINUX_2.6.39
223 .TE
224 .SS bfin (Blackfin) functions (port removed in Linux 4.17)
225 .\" See linux/arch/blackfin/kernel/fixed_code.S
226 .\" See http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code
227 As this CPU lacks a memory management unit (MMU),
228 it doesn't set up a vDSO in the normal sense.
229 Instead, it maps at boot time a few raw functions into
230 a fixed location in memory.
231 User-space applications then call directly into that region.
232 There is no provision for backward compatibility
233 beyond sniffing raw opcodes,
234 but as this is an embedded CPU, it can get away with things\[em]some of the
235 object formats it runs aren't even ELF based (they're bFLT/FLAT).
236 .P
237 For information on this code page,
238 it's best to refer to the public documentation:
239 .br
240 http://docs.blackfin.uclinux.org/doku.php?id=linux\-kernel:fixed\-code
241 .SS mips functions
242 .\" See linux/arch/mips/vdso/vdso.ld.S
243 The table below lists the symbols exported by the vDSO.
244 .P
245 .TS
246 lB lB
247 l l .
248 symbol version
249 _
250 __kernel_gettimeofday LINUX_2.6 (exported since Linux 4.4)
251 __kernel_clock_gettime LINUX_2.6 (exported since Linux 4.4)
252 .TE
253 .SS ia64 (Itanium) functions
254 .\" See linux/arch/ia64/kernel/gate.lds.S
255 .\" Also linux/arch/ia64/kernel/fsys.S and linux/Documentation/ia64/fsys.rst
256 The table below lists the symbols exported by the vDSO.
257 .P
258 .TS
259 lB lB
260 l l .
261 symbol version
262 _
263 __kernel_sigtramp LINUX_2.5
264 __kernel_syscall_via_break LINUX_2.5
265 __kernel_syscall_via_epc LINUX_2.5
266 .TE
267 .P
268 The Itanium port is somewhat tricky.
269 In addition to the vDSO above, it also has "light-weight system calls"
270 (also known as "fast syscalls" or "fsys").
271 You can invoke these via the
272 .I __kernel_syscall_via_epc
273 vDSO helper.
274 The system calls listed here have the same semantics as if you called them
275 directly via
276 .BR syscall (2),
277 so refer to the relevant
278 documentation for each.
279 The table below lists the functions available via this mechanism.
280 .P
281 .TS
282 lB
283 l .
284 function
285 _
286 clock_gettime
287 getcpu
288 getpid
289 getppid
290 gettimeofday
291 set_tid_address
292 .TE
293 .SS parisc (hppa) functions
294 .\" See linux/arch/parisc/kernel/syscall.S
295 .\" See linux/Documentation/parisc/registers.rst
296 The parisc port has a code page with utility functions
297 called a gateway page.
298 Rather than use the normal ELF auxiliary vector approach,
299 it passes the address of
300 the page to the process via the SR2 register.
301 The permissions on the page are such that merely executing those addresses
302 automatically executes with kernel privileges and not in user space.
303 This is done to match the way HP-UX works.
304 .P
305 Since it's just a raw page of code, there is no ELF information for doing
306 symbol lookups or versioning.
307 Simply call into the appropriate offset via the branch instruction,
308 for example:
309 .P
310 .in +4n
311 .EX
312 ble <offset>(%sr2, %r0)
313 .EE
314 .in
315 .P
316 .TS
317 lB lB
318 l l .
319 offset function
320 _
321 00b0 lws_entry (CAS operations)
322 00e0 set_thread_pointer (used by glibc)
323 0100 linux_gateway_entry (syscall)
324 .TE
325 .SS ppc/32 functions
326 .\" See linux/arch/powerpc/kernel/vdso32/vdso32.lds.S
327 The table below lists the symbols exported by the vDSO.
328 The functions marked with a
329 .I *
330 are available only when the kernel is
331 a PowerPC64 (64-bit) kernel.
332 .P
333 .TS
334 lB lB
335 l l .
336 symbol version
337 _
338 __kernel_clock_getres LINUX_2.6.15
339 __kernel_clock_gettime LINUX_2.6.15
340 __kernel_clock_gettime64 LINUX_5.11
341 __kernel_datapage_offset LINUX_2.6.15
342 __kernel_get_syscall_map LINUX_2.6.15
343 __kernel_get_tbfreq LINUX_2.6.15
344 __kernel_getcpu \f[I]*\f[] LINUX_2.6.15
345 __kernel_gettimeofday LINUX_2.6.15
346 __kernel_sigtramp_rt32 LINUX_2.6.15
347 __kernel_sigtramp32 LINUX_2.6.15
348 __kernel_sync_dicache LINUX_2.6.15
349 __kernel_sync_dicache_p5 LINUX_2.6.15
350 .TE
351 .P
352 Before Linux 5.6,
353 .\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39
354 the
355 .B CLOCK_REALTIME_COARSE
356 and
357 .B CLOCK_MONOTONIC_COARSE
358 clocks are
359 .I not
360 supported by the
361 .I __kernel_clock_getres
362 and
363 .I __kernel_clock_gettime
364 interfaces;
365 the kernel falls back to the real system call.
366 .SS ppc/64 functions
367 .\" See linux/arch/powerpc/kernel/vdso64/vdso64.lds.S
368 The table below lists the symbols exported by the vDSO.
369 .P
370 .TS
371 lB lB
372 l l .
373 symbol version
374 _
375 __kernel_clock_getres LINUX_2.6.15
376 __kernel_clock_gettime LINUX_2.6.15
377 __kernel_datapage_offset LINUX_2.6.15
378 __kernel_get_syscall_map LINUX_2.6.15
379 __kernel_get_tbfreq LINUX_2.6.15
380 __kernel_getcpu LINUX_2.6.15
381 __kernel_gettimeofday LINUX_2.6.15
382 __kernel_sigtramp_rt64 LINUX_2.6.15
383 __kernel_sync_dicache LINUX_2.6.15
384 __kernel_sync_dicache_p5 LINUX_2.6.15
385 .TE
386 .P
387 Before Linux 4.16,
388 .\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1
389 the
390 .B CLOCK_REALTIME_COARSE
391 and
392 .B CLOCK_MONOTONIC_COARSE
393 clocks are
394 .I not
395 supported by the
396 .I __kernel_clock_getres
397 and
398 .I __kernel_clock_gettime
399 interfaces;
400 the kernel falls back to the real system call.
401 .SS riscv functions
402 .\" See linux/arch/riscv/kernel/vdso/vdso.lds.S
403 The table below lists the symbols exported by the vDSO.
404 .P
405 .TS
406 lB lB
407 l l .
408 symbol version
409 _
410 __vdso_rt_sigreturn LINUX_4.15
411 __vdso_gettimeofday LINUX_4.15
412 __vdso_clock_gettime LINUX_4.15
413 __vdso_clock_getres LINUX_4.15
414 __vdso_getcpu LINUX_4.15
415 __vdso_flush_icache LINUX_4.15
416 .TE
417 .SS s390 functions
418 .\" See linux/arch/s390/kernel/vdso32/vdso32.lds.S
419 The table below lists the symbols exported by the vDSO.
420 .P
421 .TS
422 lB lB
423 l l .
424 symbol version
425 _
426 __kernel_clock_getres LINUX_2.6.29
427 __kernel_clock_gettime LINUX_2.6.29
428 __kernel_gettimeofday LINUX_2.6.29
429 .TE
430 .SS s390x functions
431 .\" See linux/arch/s390/kernel/vdso64/vdso64.lds.S
432 The table below lists the symbols exported by the vDSO.
433 .P
434 .TS
435 lB lB
436 l l .
437 symbol version
438 _
439 __kernel_clock_getres LINUX_2.6.29
440 __kernel_clock_gettime LINUX_2.6.29
441 __kernel_gettimeofday LINUX_2.6.29
442 .TE
443 .SS sh (SuperH) functions
444 .\" See linux/arch/sh/kernel/vsyscall/vsyscall.lds.S
445 The table below lists the symbols exported by the vDSO.
446 .P
447 .TS
448 lB lB
449 l l .
450 symbol version
451 _
452 __kernel_rt_sigreturn LINUX_2.6
453 __kernel_sigreturn LINUX_2.6
454 __kernel_vsyscall LINUX_2.6
455 .TE
456 .SS i386 functions
457 .\" See linux/arch/x86/vdso/vdso32/vdso32.lds.S
458 The table below lists the symbols exported by the vDSO.
459 .P
460 .TS
461 lB lB
462 l l .
463 symbol version
464 _
465 __kernel_sigreturn LINUX_2.5
466 __kernel_rt_sigreturn LINUX_2.5
467 __kernel_vsyscall LINUX_2.5
468 .\" Added in 7a59ed415f5b57469e22e41fc4188d5399e0b194 and updated
469 .\" in 37c975545ec63320789962bf307f000f08fabd48.
470 __vdso_clock_gettime LINUX_2.6 (exported since Linux 3.15)
471 __vdso_gettimeofday LINUX_2.6 (exported since Linux 3.15)
472 __vdso_time LINUX_2.6 (exported since Linux 3.15)
473 .TE
474 .SS x86-64 functions
475 .\" See linux/arch/x86/vdso/vdso.lds.S
476 The table below lists the symbols exported by the vDSO.
477 All of these symbols are also available without the "__vdso_" prefix, but
478 you should ignore those and stick to the names below.
479 .P
480 .TS
481 lB lB
482 l l .
483 symbol version
484 _
485 __vdso_clock_gettime LINUX_2.6
486 __vdso_getcpu LINUX_2.6
487 __vdso_gettimeofday LINUX_2.6
488 __vdso_time LINUX_2.6
489 .TE
490 .SS x86/x32 functions
491 .\" See linux/arch/x86/vdso/vdso32.lds.S
492 The table below lists the symbols exported by the vDSO.
493 .P
494 .TS
495 lB lB
496 l l .
497 symbol version
498 _
499 __vdso_clock_gettime LINUX_2.6
500 __vdso_getcpu LINUX_2.6
501 __vdso_gettimeofday LINUX_2.6
502 __vdso_time LINUX_2.6
503 .TE
504 .SS History
505 The vDSO was originally just a single function\[em]the vsyscall.
506 In older kernels, you might see that name
507 in a process's memory map rather than "vdso".
508 Over time, people realized that this mechanism
509 was a great way to pass more functionality
510 to user space, so it was reconceived as a vDSO in the current format.
511 .SH SEE ALSO
512 .BR syscalls (2),
513 .BR getauxval (3),
514 .BR proc (5)
515 .P
516 The documents, examples, and source code in the Linux source code tree:
517 .P
518 .in +4n
519 .EX
520 Documentation/ABI/stable/vdso
521 Documentation/ia64/fsys.rst
522 Documentation/vDSO/* (includes examples of using the vDSO)
523 .P
524 find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq]
525 .EE
526 .in
527 .P
528 .UR http:\://articles.manugarg.com/\:systemcallinlinux2_6.html
529 .UE
530 .P
531 .UR https:\://lwn.net/Articles/\:446528/
532 .UE
533 .P
534 .UR http:\://www.linuxjournal.com/\:content/\:creating\-vdso\-colonels\-other\-chicken
535 .UE
536 .P
537 .UR http:\://www.trilithium.com/\:johan/\:2005/\:08/\:linux\-gate/
538 .UE