2 .\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\" See also https://lwn.net/Articles/519085/
8 .TH getauxval 3 (date) "Linux man-pages (unreleased)"
10 getauxval \- retrieve a value from the auxiliary vector
13 .RI ( libc ", " \-lc )
16 .B #include <sys/auxv.h>
18 .BI "unsigned long getauxval(unsigned long " type );
23 function retrieves values from the auxiliary vector,
24 a mechanism that the kernel's ELF binary loader
25 uses to pass certain information to
26 user space when a program is executed.
28 Each entry in the auxiliary vector consists of a pair of values:
29 a type that identifies what this entry represents,
30 and a value for that type.
34 returns the corresponding value.
36 The value returned for each
38 is given in the following list.
41 values are present on all architectures.
44 The base address of the program interpreter (usually, the dynamic linker).
47 A pointer to a string (PowerPC and MIPS only).
48 On PowerPC, this identifies the real platform; may differ from
51 .\" commit e585b768da111f2c2d413de6214e83bbdfee8f22
52 this identifies the ISA level (since Linux 5.7).
55 The frequency with which
58 This value can also be obtained via
59 .IR sysconf(_SC_CLK_TCK) .
62 The data cache block size.
65 The effective group ID of the thread.
68 The entry address of the executable.
71 The effective user ID of the thread.
74 File descriptor of program.
77 A pointer to a string containing the pathname used to execute the program.
83 Used FPU control word (SuperH architecture only).
84 This gives some information about the FPU initialization
85 performed by the kernel.
88 The real group ID of the thread.
91 An architecture and ABI dependent bit-mask whose settings
92 indicate detailed processor capabilities.
93 The contents of the bit mask are hardware dependent
94 (for example, see the kernel source file
95 .I arch/x86/include/asm/cpufeature.h
96 for details relating to the Intel x86 architecture; the value
97 returned is the first 32-bit word of the array described there).
98 A human-readable version of the same information is available via
101 .BR AT_HWCAP2 " (since glibc 2.18)"
102 Further machine-dependent hints about processor capabilities.
105 The instruction cache block size.
113 .\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147
114 .B AT_L1D_CACHEGEOMETRY
115 Geometry of the L1 data cache, encoded with the cache line size in bytes
116 in the bottom 16 bits and the cache associativity in the next 16 bits.
117 The associativity is such that if N is the 16-bit value,
118 the cache is N-way set associative.
121 The L1 data cache size.
123 .B AT_L1I_CACHEGEOMETRY
124 Geometry of the L1 instruction cache, encoded as for
125 .BR AT_L1D_CACHEGEOMETRY .
128 The L1 instruction cache size.
130 .B AT_L2_CACHEGEOMETRY
131 Geometry of the L2 cache, encoded as for
132 .BR AT_L1D_CACHEGEOMETRY .
137 .B AT_L3_CACHEGEOMETRY
138 Geometry of the L3 cache, encoded as for
139 .BR AT_L1D_CACHEGEOMETRY .
145 The system page size (the same value returned by
146 .IR sysconf(_SC_PAGESIZE) ).
149 The address of the program headers of the executable.
152 The size of program header entry.
155 The number of program headers.
158 A pointer to a string that identifies the hardware platform
159 that the program is running on.
160 The dynamic linker uses this in the interpretation of
165 The address of sixteen bytes containing a random value.
168 Has a nonzero value if this executable should be treated securely.
169 Most commonly, a nonzero value indicates that the process is
170 executing a set-user-ID or set-group-ID binary
171 (so that its real and effective UIDs or GIDs differ from one another),
172 or that it gained capabilities by executing
173 a binary file that has capabilities (see
174 .BR capabilities (7)).
176 a nonzero value may be triggered by a Linux Security Module.
177 When this value is nonzero,
178 the dynamic linker disables the use of certain environment variables (see
179 .BR ld\-linux.so (8))
180 and glibc changes other aspects of its behavior.
182 .BR secure_getenv (3).)
185 The entry point to the system call function in the vDSO.
186 Not present/needed on all architectures (e.g., absent on x86-64).
189 The address of a page containing the virtual Dynamic Shared Object (vDSO)
190 that the kernel creates in order to provide fast implementations of
191 certain system calls.
194 The unified cache block size.
197 The real user ID of the thread.
201 returns the value corresponding to
205 is not found, 0 is returned.
208 .BR ENOENT " (since glibc 2.19)"
209 .\" commit b9ab448f980e296eac21ac65f53783967cc6037b
210 No entry corresponding to
212 could be found in the auxiliary vector.
214 For an explanation of the terms used in this section, see
222 Interface Attribute Value
225 T} Thread safety MT-Safe
235 The primary consumer of the information in the auxiliary vector
236 is the dynamic linker,
237 .BR ld\-linux.so (8).
238 The auxiliary vector is a convenient and efficient shortcut
239 that allows the kernel to communicate a certain set of standard
240 information that the dynamic linker usually or always needs.
241 In some cases, the same information could be obtained by system calls,
242 but using the auxiliary vector is cheaper.
244 The auxiliary vector resides just above the argument list and
245 environment in the process address space.
246 The auxiliary vector supplied to a program can be viewed by setting the
248 environment variable when running a program:
252 $ LD_SHOW_AUXV=1 sleep 1
256 The auxiliary vector of any process can (subject to file permissions)
258 .IR /proc/ pid /auxv ;
261 for more information.
263 Before the addition of the
266 there was no way to unambiguously distinguish the case where
268 could not be found from the case where the value corresponding to
273 .BR secure_getenv (3),