| .\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" See also https://lwn.net/Articles/519085/ |
| .\" |
| .TH GETAUXVAL 3 2016-07-17 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| getauxval \- retrieve a value from the auxiliary vector |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/auxv.h> |
| .sp |
| .BI "unsigned long getauxval(unsigned long " type ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR getauxval () |
| function retrieves values from the auxiliary vector, |
| a mechanism that the kernel's ELF binary loader |
| uses to pass certain information to |
| user space when a program is executed. |
| |
| Each entry in the auxiliary vector consists of a pair of values: |
| a type that identifies what this entry represents, |
| and a value for that type. |
| Given the argument |
| .IR type , |
| .BR getauxval () |
| returns the corresponding value. |
| |
| The value returned for each |
| .I type |
| is given in the following list. |
| Not all |
| .I type |
| values are present on all architectures. |
| .TP |
| .BR AT_BASE |
| The base address of the program interpreter (usually, the dynamic linker). |
| .TP |
| .BR AT_BASE_PLATFORM |
| A string identifying the real platform; may differ from |
| .BR AT_PLATFORM |
| (PowerPC only). |
| .TP |
| .BR AT_CLKTCK |
| The frequency with which |
| .BR times (2) |
| counts. |
| This value can also be obtained via |
| .IR sysconf(_SC_CLK_TCK) . |
| .TP |
| .BR AT_DCACHEBSIZE |
| The data cache block size. |
| .TP |
| .BR AT_EGID |
| The effective group ID of the thread. |
| .TP |
| .BR AT_ENTRY |
| The entry address of the executable. |
| .TP |
| .BR AT_EUID |
| The effective user ID of the thread. |
| .TP |
| .BR AT_EXECFD |
| File descriptor of program. |
| .TP |
| .BR AT_EXECFN |
| Pathname used to execute program. |
| .TP |
| .BR AT_FLAGS |
| Flags (unused). |
| .TP |
| .BR AT_FPUCW |
| Used FPU control word (SuperH architecture only). |
| This gives some information about the FPU initialization |
| performed by the kernel. |
| .TP |
| .BR AT_GID |
| The real group ID of the thread. |
| .TP |
| .BR AT_HWCAP |
| An architecture and ABI dependent bit-mask whose settings |
| indicate detailed processor capabilities. |
| The contents of the bit mask are hardware dependent |
| (for example, see the kernel source file |
| .IR arch/x86/include/asm/cpufeature.h |
| for details relating to the Intel x86 architecture; the value |
| returned is the first 32-bit word of the array described there). |
| A human-readable version of the same information is available via |
| .IR /proc/cpuinfo . |
| .TP |
| .BR AT_HWCAP2 " (since glibc 2.18)" |
| Further machine-dependent hints about processor capabilities. |
| .TP |
| .BR AT_ICACHEBSIZE |
| The instruction cache block size. |
| .\" .TP |
| .\" .BR AT_IGNORE |
| .\" .TP |
| .\" .BR AT_IGNOREPPC |
| .\" .TP |
| .\" .BR AT_NOTELF |
| .TP |
| .BR AT_PAGESZ |
| The system page size (the same value returned by |
| .IR sysconf(_SC_PAGESIZE) ). |
| .TP |
| .BR AT_PHDR |
| The address of the program headers of the executable. |
| .TP |
| .BR AT_PHENT |
| The size of program header entry. |
| .TP |
| .BR AT_PHNUM |
| The number of program headers. |
| .TP |
| .BR AT_PLATFORM |
| A pointer to a string that identifies the hardware platform |
| that the program is running on. |
| The dynamic linker uses this in the interpretation of |
| .IR rpath |
| values. |
| .TP |
| .BR AT_RANDOM |
| The address of sixteen bytes containing a random value. |
| .TP |
| .BR AT_SECURE |
| Has a nonzero value if this executable should be treated securely. |
| Most commonly, a nonzero value indicates that the process is |
| executing a set-user-ID or set-group-ID binary |
| (so that its real and effective UIDs or GIDs differ from one another), |
| or that it gained capabilities by executing |
| a binary file that has capabilities (see |
| .BR capabilities (7)). |
| Alternatively, |
| a nonzero value may be triggered by a Linux Security Module. |
| When this value is nonzero, |
| the dynamic linker disables the use of certain environment variables (see |
| .BR ld-linux.so (8)) |
| and glibc changes other aspects of its behavior. |
| (See also |
| .BR secure_getenv (3).) |
| .TP |
| .BR AT_SYSINFO |
| The entry point to the system call function in the vDSO. |
| Not present/needed on all architectures (e.g., absent on x86-64). |
| .TP |
| .BR AT_SYSINFO_EHDR |
| The address of a page containing the virtual Dynamic Shared Object (vDSO) |
| that the kernel creates in order to provide fast implementations of |
| certain system calls. |
| .TP |
| .BR AT_UCACHEBSIZE |
| The unified cache block size. |
| .TP |
| .BR AT_UID |
| The real user ID of the thread. |
| .SH RETURN VALUE |
| On success, |
| .BR getauxval () |
| returns the value corresponding to |
| .IR type . |
| If |
| .I type |
| is not found, 0 is returned. |
| .SH ERRORS |
| .TP |
| .BR ENOENT " (since glibc 2.19)" |
| .\" commit b9ab448f980e296eac21ac65f53783967cc6037b |
| No entry corresponding to |
| .IR type |
| could be found in the auxiliary vector. |
| .SH VERSIONS |
| The |
| .BR getauxval () |
| function was added to glibc in version 2.16. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lb lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR getauxval () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| This function is a nonstandard glibc extension. |
| .SH NOTES |
| The primary consumer of the information in the auxiliary vector |
| is the dynamic linker |
| .BR ld-linux.so (8). |
| The auxiliary vector is a convenient and efficient shortcut |
| that allows the kernel to communicate a certain set of standard |
| information that the dynamic linker usually or always needs. |
| In some cases, the same information could be obtained by system calls, |
| but using the auxiliary vector is cheaper. |
| |
| The auxiliary vector resides just above the argument list and |
| environment in the process address space. |
| The auxiliary vector supplied to a program can be viewed by setting the |
| .B LD_SHOW_AUXV |
| environment variable when running a program: |
| |
| $ LD_SHOW_AUXV=1 sleep 1 |
| |
| The auxiliary vector of any process can (subject to file permissions) |
| be obtained via |
| .IR /proc/PID/auxv ; |
| see |
| .BR proc (5) |
| for more information. |
| .SH BUGS |
| Before the addition of the |
| .B ENOENT |
| error in glibc 2.19, |
| there was no way to unambiguously distinguish the case where |
| .I type |
| could not be found from the case where the value corresponding to |
| .I type |
| was zero. |
| .SH SEE ALSO |
| .BR secure_getenv (3), |
| .BR vdso (7), |
| .BR ld-linux.so (8) |