Debian Codegraph @

upstream/debian-unstable/man3/getauxval.3

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