]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
4946106c MK |
2 | .\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
4946106c MK |
5 | .\" |
6 | .\" See also https://lwn.net/Articles/519085/ | |
7 | .\" | |
a5ebdc8d | 8 | .TH getauxval 3 (date) "Linux man-pages (unreleased)" |
4946106c MK |
9 | .SH NAME |
10 | getauxval \- retrieve a value from the auxiliary vector | |
cfba38f4 AC |
11 | .SH LIBRARY |
12 | Standard C library | |
13 | .RI ( libc ", " \-lc ) | |
4946106c MK |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <sys/auxv.h> | |
68e4db0a | 17 | .PP |
4946106c MK |
18 | .BI "unsigned long getauxval(unsigned long " type ); |
19 | .fi | |
20 | .SH DESCRIPTION | |
21 | The | |
22 | .BR getauxval () | |
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. | |
847e0d88 | 27 | .PP |
4946106c MK |
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. | |
31 | Given the argument | |
32 | .IR type , | |
33 | .BR getauxval () | |
34 | returns the corresponding value. | |
847e0d88 | 35 | .PP |
4946106c MK |
36 | The value returned for each |
37 | .I type | |
38 | is given in the following list. | |
39 | Not all | |
40 | .I type | |
41 | values are present on all architectures. | |
42 | .TP | |
1ae6b2c7 | 43 | .B AT_BASE |
4946106c MK |
44 | The base address of the program interpreter (usually, the dynamic linker). |
45 | .TP | |
1ae6b2c7 | 46 | .B AT_BASE_PLATFORM |
685385df YS |
47 | A pointer to a string (PowerPC and MIPS only). |
48 | On PowerPC, this identifies the real platform; may differ from | |
49 | .BR AT_PLATFORM "." | |
40ce7414 MK |
50 | On MIPS, |
51 | .\" commit e585b768da111f2c2d413de6214e83bbdfee8f22 | |
52 | this identifies the ISA level (since Linux 5.7). | |
4946106c | 53 | .TP |
1ae6b2c7 | 54 | .B AT_CLKTCK |
4946106c MK |
55 | The frequency with which |
56 | .BR times (2) | |
57 | counts. | |
58 | This value can also be obtained via | |
59 | .IR sysconf(_SC_CLK_TCK) . | |
60 | .TP | |
1ae6b2c7 | 61 | .B AT_DCACHEBSIZE |
4946106c MK |
62 | The data cache block size. |
63 | .TP | |
1ae6b2c7 | 64 | .B AT_EGID |
4946106c MK |
65 | The effective group ID of the thread. |
66 | .TP | |
1ae6b2c7 | 67 | .B AT_ENTRY |
4946106c MK |
68 | The entry address of the executable. |
69 | .TP | |
1ae6b2c7 | 70 | .B AT_EUID |
4946106c MK |
71 | The effective user ID of the thread. |
72 | .TP | |
1ae6b2c7 | 73 | .B AT_EXECFD |
4946106c MK |
74 | File descriptor of program. |
75 | .TP | |
1ae6b2c7 | 76 | .B AT_EXECFN |
0b1348ba | 77 | A pointer to a string containing the pathname used to execute the program. |
4946106c | 78 | .TP |
1ae6b2c7 | 79 | .B AT_FLAGS |
4946106c MK |
80 | Flags (unused). |
81 | .TP | |
1ae6b2c7 | 82 | .B AT_FPUCW |
fa1d2749 | 83 | Used FPU control word (SuperH architecture only). |
4946106c MK |
84 | This gives some information about the FPU initialization |
85 | performed by the kernel. | |
86 | .TP | |
1ae6b2c7 | 87 | .B AT_GID |
4946106c MK |
88 | The real group ID of the thread. |
89 | .TP | |
1ae6b2c7 | 90 | .B AT_HWCAP |
7e318d44 | 91 | An architecture and ABI dependent bit-mask whose settings |
4946106c MK |
92 | indicate detailed processor capabilities. |
93 | The contents of the bit mask are hardware dependent | |
94 | (for example, see the kernel source file | |
1ae6b2c7 | 95 | .I arch/x86/include/asm/cpufeature.h |
063bf5a7 | 96 | for details relating to the Intel x86 architecture; the value |
291415ef | 97 | returned is the first 32-bit word of the array described there). |
4946106c MK |
98 | A human-readable version of the same information is available via |
99 | .IR /proc/cpuinfo . | |
100 | .TP | |
2e380e89 MK |
101 | .BR AT_HWCAP2 " (since glibc 2.18)" |
102 | Further machine-dependent hints about processor capabilities. | |
103 | .TP | |
1ae6b2c7 | 104 | .B AT_ICACHEBSIZE |
4946106c MK |
105 | The instruction cache block size. |
106 | .\" .TP | |
107 | .\" .BR AT_IGNORE | |
108 | .\" .TP | |
109 | .\" .BR AT_IGNOREPPC | |
110 | .\" .TP | |
111 | .\" .BR AT_NOTELF | |
112 | .TP | |
a81869d0 | 113 | .\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147 |
1ae6b2c7 | 114 | .B AT_L1D_CACHEGEOMETRY |
be2e899b MK |
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. | |
a81869d0 | 119 | .TP |
1ae6b2c7 | 120 | .B AT_L1D_CACHESIZE |
a81869d0 RMZ |
121 | The L1 data cache size. |
122 | .TP | |
1ae6b2c7 | 123 | .B AT_L1I_CACHEGEOMETRY |
618b1e7e MK |
124 | Geometry of the L1 instruction cache, encoded as for |
125 | .BR AT_L1D_CACHEGEOMETRY . | |
a81869d0 | 126 | .TP |
1ae6b2c7 | 127 | .B AT_L1I_CACHESIZE |
a81869d0 RMZ |
128 | The L1 instruction cache size. |
129 | .TP | |
1ae6b2c7 | 130 | .B AT_L2_CACHEGEOMETRY |
618b1e7e MK |
131 | Geometry of the L2 cache, encoded as for |
132 | .BR AT_L1D_CACHEGEOMETRY . | |
a81869d0 | 133 | .TP |
1ae6b2c7 | 134 | .B AT_L2_CACHESIZE |
a81869d0 RMZ |
135 | The L2 cache size. |
136 | .TP | |
1ae6b2c7 | 137 | .B AT_L3_CACHEGEOMETRY |
618b1e7e MK |
138 | Geometry of the L3 cache, encoded as for |
139 | .BR AT_L1D_CACHEGEOMETRY . | |
a81869d0 | 140 | .TP |
1ae6b2c7 | 141 | .B AT_L3_CACHESIZE |
a81869d0 RMZ |
142 | The L3 cache size. |
143 | .TP | |
1ae6b2c7 | 144 | .B AT_PAGESZ |
4946106c | 145 | The system page size (the same value returned by |
1e4a9e18 | 146 | .IR sysconf(_SC_PAGESIZE) ). |
4946106c | 147 | .TP |
1ae6b2c7 | 148 | .B AT_PHDR |
4946106c MK |
149 | The address of the program headers of the executable. |
150 | .TP | |
1ae6b2c7 | 151 | .B AT_PHENT |
4946106c MK |
152 | The size of program header entry. |
153 | .TP | |
1ae6b2c7 | 154 | .B AT_PHNUM |
4946106c MK |
155 | The number of program headers. |
156 | .TP | |
1ae6b2c7 | 157 | .B AT_PLATFORM |
4946106c MK |
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 | |
1ae6b2c7 | 161 | .I rpath |
4946106c MK |
162 | values. |
163 | .TP | |
1ae6b2c7 | 164 | .B AT_RANDOM |
4946106c MK |
165 | The address of sixteen bytes containing a random value. |
166 | .TP | |
1ae6b2c7 | 167 | .B AT_SECURE |
4946106c MK |
168 | Has a nonzero value if this executable should be treated securely. |
169 | Most commonly, a nonzero value indicates that the process is | |
422dd47f | 170 | executing a set-user-ID or set-group-ID binary |
36f99b92 | 171 | (so that its real and effective UIDs or GIDs differ from one another), |
422dd47f MK |
172 | or that it gained capabilities by executing |
173 | a binary file that has capabilities (see | |
6912d54f MK |
174 | .BR capabilities (7)). |
175 | Alternatively, | |
4946106c MK |
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 | |
28a4c58c | 179 | .BR ld\-linux.so (8)) |
fa1d2749 | 180 | and glibc changes other aspects of its behavior. |
4946106c MK |
181 | (See also |
182 | .BR secure_getenv (3).) | |
183 | .TP | |
1ae6b2c7 | 184 | .B AT_SYSINFO |
5d4708c3 | 185 | The entry point to the system call function in the vDSO. |
4946106c MK |
186 | Not present/needed on all architectures (e.g., absent on x86-64). |
187 | .TP | |
1ae6b2c7 | 188 | .B AT_SYSINFO_EHDR |
5d4708c3 | 189 | The address of a page containing the virtual Dynamic Shared Object (vDSO) |
4946106c MK |
190 | that the kernel creates in order to provide fast implementations of |
191 | certain system calls. | |
192 | .TP | |
1ae6b2c7 | 193 | .B AT_UCACHEBSIZE |
4946106c MK |
194 | The unified cache block size. |
195 | .TP | |
1ae6b2c7 | 196 | .B AT_UID |
4946106c MK |
197 | The real user ID of the thread. |
198 | .SH RETURN VALUE | |
199 | On success, | |
200 | .BR getauxval () | |
201 | returns the value corresponding to | |
202 | .IR type . | |
203 | If | |
204 | .I type | |
205 | is not found, 0 is returned. | |
206 | .SH ERRORS | |
89c1cb59 MK |
207 | .TP |
208 | .BR ENOENT " (since glibc 2.19)" | |
209 | .\" commit b9ab448f980e296eac21ac65f53783967cc6037b | |
210 | No entry corresponding to | |
1ae6b2c7 | 211 | .I type |
89c1cb59 | 212 | could be found in the auxiliary vector. |
b727421c | 213 | .SH ATTRIBUTES |
8c5731ff MK |
214 | For an explanation of the terms used in this section, see |
215 | .BR attributes (7). | |
216 | .TS | |
217 | allbox; | |
c466875e | 218 | lbx lb lb |
8c5731ff MK |
219 | l l l. |
220 | Interface Attribute Value | |
221 | T{ | |
9e54434e BR |
222 | .na |
223 | .nh | |
b727421c | 224 | .BR getauxval () |
8c5731ff MK |
225 | T} Thread safety MT-Safe |
226 | .TE | |
c466875e | 227 | .sp 1 |
3113c7f3 | 228 | .SH STANDARDS |
4131356c AC |
229 | GNU. |
230 | .SH HISTORY | |
231 | glibc 2.16. | |
4946106c MK |
232 | .SH NOTES |
233 | The primary consumer of the information in the auxiliary vector | |
df022779 | 234 | is the dynamic linker, |
28a4c58c | 235 | .BR ld\-linux.so (8). |
4946106c MK |
236 | The auxiliary vector is a convenient and efficient shortcut |
237 | that allows the kernel to communicate a certain set of standard | |
238 | information that the dynamic linker usually or always needs. | |
239 | In some cases, the same information could be obtained by system calls, | |
240 | but using the auxiliary vector is cheaper. | |
847e0d88 | 241 | .PP |
4946106c MK |
242 | The auxiliary vector resides just above the argument list and |
243 | environment in the process address space. | |
244 | The auxiliary vector supplied to a program can be viewed by setting the | |
245 | .B LD_SHOW_AUXV | |
246 | environment variable when running a program: | |
019d9ee8 MK |
247 | .PP |
248 | .in +4n | |
249 | .EX | |
250 | $ LD_SHOW_AUXV=1 sleep 1 | |
251 | .EE | |
252 | .in | |
253 | .PP | |
4946106c MK |
254 | The auxiliary vector of any process can (subject to file permissions) |
255 | be obtained via | |
0d782b8d | 256 | .IR /proc/ pid /auxv ; |
4946106c MK |
257 | see |
258 | .BR proc (5) | |
259 | for more information. | |
89c1cb59 MK |
260 | .SH BUGS |
261 | Before the addition of the | |
262 | .B ENOENT | |
263 | error in glibc 2.19, | |
264 | there was no way to unambiguously distinguish the case where | |
265 | .I type | |
266 | could not be found from the case where the value corresponding to | |
267 | .I type | |
a03a7435 | 268 | was zero. |
47297adb | 269 | .SH SEE ALSO |
dc3037bf | 270 | .BR execve (2), |
4946106c | 271 | .BR secure_getenv (3), |
951ae9c0 | 272 | .BR vdso (7), |
28a4c58c | 273 | .BR ld\-linux.so (8) |