{ "content": [ { "type": "text", "text": "# vdso(7) (man)\n\n**Summary:** vdso - overview of the virtual ELF dynamic shared object\n\n## See Also\n\n- syscalls(2)\n- getauxval(3)\n- proc(5)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (1 lines) — 1 subsections\n - #include (2 lines)\n- **DESCRIPTION** (15 lines) — 3 subsections\n - Example background (21 lines)\n - Finding the vDSO (13 lines)\n - File format (17 lines)\n- **NOTES** (1 lines) — 3 subsections\n - Source (5 lines)\n - vDSO names (19 lines)\n - strace(1), seccomp(2), and the vDSO (4 lines)\n- **ARCHITECTURE-SPECIFIC NOTES** (8 lines) — 16 subsections\n - ARM functions (15 lines)\n - aarch64 functions (9 lines)\n - bfin (Blackfin) functions (port removed in Linux 4.17) (10 lines)\n - mips functions (7 lines)\n - ia64 (Itanium) functions (23 lines)\n - parisc (hppa) functions (17 lines)\n - ppc/32 functions (21 lines)\n - ppc/64 functions (19 lines)\n - riscv functions (11 lines)\n - s390 functions (9 lines)\n - s390x functions (8 lines)\n - sh (SuperH) functions (8 lines)\n - i386 functions (11 lines)\n - x86-64 functions (10 lines)\n - x86/x32 functions (9 lines)\n - History (5 lines)\n- **SEE ALSO** (10 lines)\n- **COLOPHON** (7 lines)\n\n## Full Content\n\n### NAME\n\nvdso - overview of the virtual ELF dynamic shared object\n\n### SYNOPSIS\n\n#### #include \n\nvoid *vdso = (uintptrt) getauxval(ATSYSINFOEHDR);\n\n### DESCRIPTION\n\nThe \"vDSO\" (virtual dynamic shared object) is a small shared library that the kernel automat‐\nically maps into the address space of all user-space applications. Applications usually do\nnot need to concern themselves with these details as the vDSO is most commonly called by the\nC library. This way you can code in the normal way using standard functions and the C li‐\nbrary will take care of using any functionality that is available via the vDSO.\n\nWhy does the vDSO exist at all? There are some system calls the kernel provides that user-\nspace code ends up using frequently, to the point that such calls can dominate overall per‐\nformance. This is due both to the frequency of the call as well as the context-switch over‐\nhead that results from exiting user space and entering the kernel.\n\nThe rest of this documentation is geared toward the curious and/or C library writers rather\nthan general developers. If you're trying to call the vDSO in your own application rather\nthan using the C library, you're most likely doing it wrong.\n\n#### Example background\n\nMaking system calls can be slow. In x86 32-bit systems, you can trigger a software interrupt\n(int $0x80) to tell the kernel you wish to make a system call. However, this instruction is\nexpensive: it goes through the full interrupt-handling paths in the processor's microcode as\nwell as in the kernel. Newer processors have faster (but backward incompatible) instructions\nto initiate system calls. Rather than require the C library to figure out if this function‐\nality is available at run time, the C library can use functions provided by the kernel in the\nvDSO.\n\nNote that the terminology can be confusing. On x86 systems, the vDSO function used to deter‐\nmine the preferred method of making a system call is named \"kernelvsyscall\", but on\nx86-64, the term \"vsyscall\" also refers to an obsolete way to ask the kernel what time it is\nor what CPU the caller is on.\n\nOne frequently used system call is gettimeofday(2). This system call is called both directly\nby user-space applications as well as indirectly by the C library. Think timestamps or tim‐\ning loops or polling—all of these frequently need to know what time it is right now. This\ninformation is also not secret—any application in any privilege mode (root or any unprivi‐\nleged user) will get the same answer. Thus the kernel arranges for the information required\nto answer this question to be placed in memory the process can access. Now a call to get‐‐\ntimeofday(2) changes from a system call to a normal function call and a few memory accesses.\n\n#### Finding the vDSO\n\nThe base address of the vDSO (if one exists) is passed by the kernel to each program in the\ninitial auxiliary vector (see getauxval(3)), via the ATSYSINFOEHDR tag.\n\nYou must not assume the vDSO is mapped at any particular location in the user's memory map.\nThe base address will usually be randomized at run time every time a new process image is\ncreated (at execve(2) time). This is done for security reasons, to prevent \"return-to-libc\"\nattacks.\n\nFor some architectures, there is also an ATSYSINFO tag. This is used only for locating the\nvsyscall entry point and is frequently omitted or set to 0 (meaning it's not available).\nThis tag is a throwback to the initial vDSO work (see History below) and its use should be\navoided.\n\n#### File format\n\nSince the vDSO is a fully formed ELF image, you can do symbol lookups on it. This allows new\nsymbols to be added with newer kernel releases, and allows the C library to detect available\nfunctionality at run time when running under different kernel versions. Oftentimes the C li‐\nbrary will do detection with the first call and then cache the result for subsequent calls.\n\nAll symbols are also versioned (using the GNU version format). This allows the kernel to up‐\ndate the function signature without breaking backward compatibility. This means changing the\narguments that the function accepts as well as the return value. Thus, when looking up a\nsymbol in the vDSO, you must always include the version to match the ABI you expect.\n\nTypically the vDSO follows the naming convention of prefixing all symbols with \"vdso\" or\n\"kernel\" so as to distinguish them from other standard symbols. For example, the \"get‐\ntimeofday\" function is named \"vdsogettimeofday\".\n\nYou use the standard C calling conventions when calling any of these functions. No need to\nworry about weird register or stack behavior.\n\n### NOTES\n\n#### Source\n\nWhen you compile the kernel, it will automatically compile and link the vDSO code for you.\nYou will frequently find it under the architecture-specific directory:\n\nfind arch/$ARCH/ -name '*vdso*.so*' -o -name '*gate*.so*'\n\n#### vDSO names\n\nThe name of the vDSO varies across architectures. It will often show up in things like\nglibc's ldd(1) output. The exact name should not matter to any code, so do not hardcode it.\n\nuser ABI vDSO name\n─────────────────────────────\naarch64 linux-vdso.so.1\narm linux-vdso.so.1\nia64 linux-gate.so.1\nmips linux-vdso.so.1\nppc/32 linux-vdso32.so.1\nppc/64 linux-vdso64.so.1\nriscv linux-vdso.so.1\ns390 linux-vdso32.so.1\ns390x linux-vdso64.so.1\nsh linux-gate.so.1\ni386 linux-gate.so.1\nx86-64 linux-vdso.so.1\nx86/x32 linux-vdso.so.1\n\n#### strace(1), seccomp(2), and the vDSO\n\nWhen tracing systems calls with strace(1), symbols (system calls) that are exported by the\nvDSO will not appear in the trace output. Those system calls will likewise not be visible to\nseccomp(2) filters.\n\n### ARCHITECTURE-SPECIFIC NOTES\n\nThe subsections below provide architecture-specific notes on the vDSO.\n\nNote that the vDSO that is used is based on the ABI of your user-space code and not the ABI\nof the kernel. Thus, for example, when you run an i386 32-bit ELF binary, you'll get the\nsame vDSO regardless of whether you run it under an i386 32-bit kernel or under an x86-64\n64-bit kernel. Therefore, the name of the user-space ABI should be used to determine which\nof the sections below is relevant.\n\n#### ARM functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n────────────────────────────────────────────────────────────\nvdsogettimeofday LINUX2.6 (exported since Linux 4.1)\nvdsoclockgettime LINUX2.6 (exported since Linux 4.1)\n\nAdditionally, the ARM port has a code page full of utility functions. Since it's just a raw\npage of code, there is no ELF information for doing symbol lookups or versioning. It does\nprovide support for different versions though.\n\nFor information on this code page, it's best to refer to the kernel documentation as it's ex‐\ntremely detailed and covers everything you need to know: Documentation/arm/ker‐\nneluserhelpers.txt.\n\n#### aarch64 functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n──────────────────────────────────────\nkernelrtsigreturn LINUX2.6.39\nkernelgettimeofday LINUX2.6.39\nkernelclockgettime LINUX2.6.39\nkernelclockgetres LINUX2.6.39\n\n#### bfin (Blackfin) functions (port removed in Linux 4.17)\n\nAs this CPU lacks a memory management unit (MMU), it doesn't set up a vDSO in the normal\nsense. Instead, it maps at boot time a few raw functions into a fixed location in memory.\nUser-space applications then call directly into that region. There is no provision for back‐\nward compatibility beyond sniffing raw opcodes, but as this is an embedded CPU, it can get\naway with things—some of the object formats it runs aren't even ELF based (they're\nbFLT/FLAT).\n\nFor information on this code page, it's best to refer to the public documentation:\nhttp://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code\n\n#### mips functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n──────────────────────────────────────────────────────────────\nkernelgettimeofday LINUX2.6 (exported since Linux 4.4)\nkernelclockgettime LINUX2.6 (exported since Linux 4.4)\n\n#### ia64 (Itanium) functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n───────────────────────────────────────\nkernelsigtramp LINUX2.5\nkernelsyscallviabreak LINUX2.5\nkernelsyscallviaepc LINUX2.5\n\nThe Itanium port is somewhat tricky. In addition to the vDSO above, it also has \"light-\nweight system calls\" (also known as \"fast syscalls\" or \"fsys\"). You can invoke these via the\nkernelsyscallviaepc vDSO helper. The system calls listed here have the same semantics\nas if you called them directly via syscall(2), so refer to the relevant documentation for\neach. The table below lists the functions available via this mechanism.\n\nfunction\n────────────────\nclockgettime\ngetcpu\ngetpid\ngetppid\ngettimeofday\nsettidaddress\n\n#### parisc (hppa) functions\n\nThe parisc port has a code page with utility functions called a gateway page. Rather than\nuse the normal ELF auxiliary vector approach, it passes the address of the page to the\nprocess via the SR2 register. The permissions on the page are such that merely executing\nthose addresses automatically executes with kernel privileges and not in user space. This is\ndone to match the way HP-UX works.\n\nSince it's just a raw page of code, there is no ELF information for doing symbol lookups or\nversioning. Simply call into the appropriate offset via the branch instruction, for example:\n\nble (%sr2, %r0)\n\noffset function\n────────────────────────────────────────────\n00b0 lwsentry (CAS operations)\n00e0 setthreadpointer (used by glibc)\n0100 linuxgatewayentry (syscall)\n\n#### ppc/32 functions\n\nThe table below lists the symbols exported by the vDSO. The functions marked with a * are\navailable only when the kernel is a PowerPC64 (64-bit) kernel.\n\nsymbol version\n────────────────────────────────────────\nkernelclockgetres LINUX2.6.15\nkernelclockgettime LINUX2.6.15\nkerneldatapageoffset LINUX2.6.15\nkernelgetsyscallmap LINUX2.6.15\nkernelgettbfreq LINUX2.6.15\nkernelgetcpu * LINUX2.6.15\nkernelgettimeofday LINUX2.6.15\nkernelsigtramprt32 LINUX2.6.15\nkernelsigtramp32 LINUX2.6.15\nkernelsyncdicache LINUX2.6.15\nkernelsyncdicachep5 LINUX2.6.15\n\nThe CLOCKREALTIMECOARSE and CLOCKMONOTONICCOARSE clocks are not supported by the ker‐\nnelclockgetres and kernelclockgettime interfaces; the kernel falls back to the real\nsystem call.\n\n#### ppc/64 functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n────────────────────────────────────────\nkernelclockgetres LINUX2.6.15\nkernelclockgettime LINUX2.6.15\nkerneldatapageoffset LINUX2.6.15\nkernelgetsyscallmap LINUX2.6.15\nkernelgettbfreq LINUX2.6.15\nkernelgetcpu LINUX2.6.15\nkernelgettimeofday LINUX2.6.15\nkernelsigtramprt64 LINUX2.6.15\nkernelsyncdicache LINUX2.6.15\nkernelsyncdicachep5 LINUX2.6.15\n\nThe CLOCKREALTIMECOARSE and CLOCKMONOTONICCOARSE clocks are not supported by the ker‐\nnelclockgetres and kernelclockgettime interfaces; the kernel falls back to the real\nsystem call.\n\n#### riscv functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n────────────────────────────────────\nkernelrtsigreturn LINUX4.15\nkernelgettimeofday LINUX4.15\nkernelclockgettime LINUX4.15\nkernelclockgetres LINUX4.15\nkernelgetcpu LINUX4.15\nkernelflushicache LINUX4.15\n\n#### s390 functions\n\nThe table below lists the symbols exported by the vDSO.\n\n\nsymbol version\n──────────────────────────────────────\nkernelclockgetres LINUX2.6.29\nkernelclockgettime LINUX2.6.29\nkernelgettimeofday LINUX2.6.29\n\n#### s390x functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n──────────────────────────────────────\nkernelclockgetres LINUX2.6.29\nkernelclockgettime LINUX2.6.29\nkernelgettimeofday LINUX2.6.29\n\n#### sh (SuperH) functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n──────────────────────────────────\nkernelrtsigreturn LINUX2.6\nkernelsigreturn LINUX2.6\nkernelvsyscall LINUX2.6\n\n#### i386 functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n──────────────────────────────────────────────────────────────\nkernelsigreturn LINUX2.5\nkernelrtsigreturn LINUX2.5\nkernelvsyscall LINUX2.5\nvdsoclockgettime LINUX2.6 (exported since Linux 3.15)\nvdsogettimeofday LINUX2.6 (exported since Linux 3.15)\nvdsotime LINUX2.6 (exported since Linux 3.15)\n\n#### x86-64 functions\n\nThe table below lists the symbols exported by the vDSO. All of these symbols are also avail‐\nable without the \"vdso\" prefix, but you should ignore those and stick to the names below.\n\nsymbol version\n─────────────────────────────────\nvdsoclockgettime LINUX2.6\nvdsogetcpu LINUX2.6\nvdsogettimeofday LINUX2.6\nvdsotime LINUX2.6\n\n#### x86/x32 functions\n\nThe table below lists the symbols exported by the vDSO.\n\nsymbol version\n─────────────────────────────────\nvdsoclockgettime LINUX2.6\nvdsogetcpu LINUX2.6\nvdsogettimeofday LINUX2.6\nvdsotime LINUX2.6\n\n#### History\n\nThe vDSO was originally just a single function—the vsyscall. In older kernels, you might see\nthat name in a process's memory map rather than \"vdso\". Over time, people realized that this\nmechanism was a great way to pass more functionality to user space, so it was reconceived as\na vDSO in the current format.\n\n### SEE ALSO\n\nsyscalls(2), getauxval(3), proc(5)\n\nThe documents, examples, and source code in the Linux source code tree:\n\nDocumentation/ABI/stable/vdso\nDocumentation/ia64/fsys.txt\nDocumentation/vDSO/* (includes examples of using the vDSO)\n\nfind arch/ -iname '*vdso*' -o -iname '*gate*'\n\n### COLOPHON\n\nThis page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2019-08-02 VDSO(7)\n\n" } ], "structuredContent": { "command": "vdso", "section": "7", "mode": "man", "summary": "vdso - overview of the virtual ELF dynamic shared object", "synopsis": "", "flags": [], "examples": [], "see_also": [ { "name": "syscalls", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/syscalls/2/json" }, { "name": "getauxval", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/getauxval/3/json" }, { "name": "proc", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/proc/5/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "#include ", "lines": 2 } ] }, { "name": "DESCRIPTION", "lines": 15, "subsections": [ { "name": "Example background", "lines": 21 }, { "name": "Finding the vDSO", "lines": 13 }, { "name": "File format", "lines": 17 } ] }, { "name": "NOTES", "lines": 1, "subsections": [ { "name": "Source", "lines": 5 }, { "name": "vDSO names", "lines": 19 }, { "name": "strace(1), seccomp(2), and the vDSO", "lines": 4 } ] }, { "name": "ARCHITECTURE-SPECIFIC NOTES", "lines": 8, "subsections": [ { "name": "ARM functions", "lines": 15 }, { "name": "aarch64 functions", "lines": 9 }, { "name": "bfin (Blackfin) functions (port removed in Linux 4.17)", "lines": 10 }, { "name": "mips functions", "lines": 7 }, { "name": "ia64 (Itanium) functions", "lines": 23 }, { "name": "parisc (hppa) functions", "lines": 17 }, { "name": "ppc/32 functions", "lines": 21 }, { "name": "ppc/64 functions", "lines": 19 }, { "name": "riscv functions", "lines": 11 }, { "name": "s390 functions", "lines": 9 }, { "name": "s390x functions", "lines": 8 }, { "name": "sh (SuperH) functions", "lines": 8 }, { "name": "i386 functions", "lines": 11 }, { "name": "x86-64 functions", "lines": 10 }, { "name": "x86/x32 functions", "lines": 9 }, { "name": "History", "lines": 5 } ] }, { "name": "SEE ALSO", "lines": 10, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ] } }