diff options
Diffstat (limited to 'man3/getauxval.3')
| -rw-r--r-- | man3/getauxval.3 | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/man3/getauxval.3 b/man3/getauxval.3 new file mode 100644 index 0000000..8e7d5e4 --- /dev/null +++ b/man3/getauxval.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" See also https://lwn.net/Articles/519085/ +.\" +.TH getauxval 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +getauxval \- retrieve a value from the auxiliary vector +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/auxv.h> +.PP +.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. +.PP +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. +.PP +The value returned for each +.I type +is given in the following list. +Not all +.I type +values are present on all architectures. +.TP +.B AT_BASE +The base address of the program interpreter (usually, the dynamic linker). +.TP +.B AT_BASE_PLATFORM +A pointer to a string (PowerPC and MIPS only). +On PowerPC, this identifies the real platform; may differ from +.BR AT_PLATFORM "." +On MIPS, +.\" commit e585b768da111f2c2d413de6214e83bbdfee8f22 +this identifies the ISA level (since Linux 5.7). +.TP +.B AT_CLKTCK +The frequency with which +.BR times (2) +counts. +This value can also be obtained via +.IR sysconf(_SC_CLK_TCK) . +.TP +.B AT_DCACHEBSIZE +The data cache block size. +.TP +.B AT_EGID +The effective group ID of the thread. +.TP +.B AT_ENTRY +The entry address of the executable. +.TP +.B AT_EUID +The effective user ID of the thread. +.TP +.B AT_EXECFD +File descriptor of program. +.TP +.B AT_EXECFN +A pointer to a string containing the pathname used to execute the program. +.TP +.B AT_FLAGS +Flags (unused). +.TP +.B AT_FPUCW +Used FPU control word (SuperH architecture only). +This gives some information about the FPU initialization +performed by the kernel. +.TP +.B AT_GID +The real group ID of the thread. +.TP +.B 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 +.I 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 +.B AT_ICACHEBSIZE +The instruction cache block size. +.\" .TP +.\" .BR AT_IGNORE +.\" .TP +.\" .BR AT_IGNOREPPC +.\" .TP +.\" .BR AT_NOTELF +.TP +.\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147 +.B AT_L1D_CACHEGEOMETRY +Geometry of the L1 data cache, encoded with the cache line size in bytes +in the bottom 16 bits and the cache associativity in the next 16 bits. +The associativity is such that if N is the 16-bit value, +the cache is N-way set associative. +.TP +.B AT_L1D_CACHESIZE +The L1 data cache size. +.TP +.B AT_L1I_CACHEGEOMETRY +Geometry of the L1 instruction cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L1I_CACHESIZE +The L1 instruction cache size. +.TP +.B AT_L2_CACHEGEOMETRY +Geometry of the L2 cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L2_CACHESIZE +The L2 cache size. +.TP +.B AT_L3_CACHEGEOMETRY +Geometry of the L3 cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L3_CACHESIZE +The L3 cache size. +.TP +.B AT_PAGESZ +The system page size (the same value returned by +.IR sysconf(_SC_PAGESIZE) ). +.TP +.B AT_PHDR +The address of the program headers of the executable. +.TP +.B AT_PHENT +The size of program header entry. +.TP +.B AT_PHNUM +The number of program headers. +.TP +.B 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 +.I rpath +values. +.TP +.B AT_RANDOM +The address of sixteen bytes containing a random value. +.TP +.B 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 +.B 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 +.B 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 +.B AT_UCACHEBSIZE +The unified cache block size. +.TP +.B 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 +.I type +could be found in the auxiliary vector. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getauxval () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.16. +.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. +.PP +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: +.PP +.in +4n +.EX +$ LD_SHOW_AUXV=1 sleep 1 +.EE +.in +.PP +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 execve (2), +.BR secure_getenv (3), +.BR vdso (7), +.BR ld\-linux.so (8) |