| blob | 082d9586a9fb0e130e323ef4095df68bf4e01f78 |
1 '\" t
2 .\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" See also https://lwn.net/Articles/519085/
7 .\"
8 .TH getauxval 3 (date) "Linux man-pages (unreleased)"
9 .SH NAME
10 getauxval \- retrieve a value from the auxiliary vector
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ", " \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/auxv.h>
17 .P
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.
27 .P
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.
35 .P
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
43 .B AT_BASE
44 The base address of the program interpreter (usually, the dynamic linker).
45 .TP
46 .B AT_BASE_PLATFORM
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 "."
50 On MIPS,
51 .\" commit e585b768da111f2c2d413de6214e83bbdfee8f22
52 this identifies the ISA level (since Linux 5.7).
53 .TP
54 .B AT_CLKTCK
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
61 .B AT_DCACHEBSIZE
62 The data cache block size.
63 .TP
64 .B AT_EGID
65 The effective group ID of the thread.
66 .TP
67 .B AT_ENTRY
68 The entry address of the executable.
69 .TP
70 .B AT_EUID
71 The effective user ID of the thread.
72 .TP
73 .B AT_EXECFD
74 File descriptor of program.
75 .TP
76 .B AT_EXECFN
77 A pointer to a string containing the pathname used to execute the program.
78 .TP
79 .B AT_FLAGS
80 Flags (unused).
81 .TP
82 .B AT_FPUCW
83 Used FPU control word (SuperH architecture only).
84 This gives some information about the FPU initialization
85 performed by the kernel.
86 .TP
87 .B AT_GID
88 The real group ID of the thread.
89 .TP
90 .B AT_HWCAP
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
99 .IR /proc/cpuinfo .
100 .TP
101 .BR AT_HWCAP2 " (since glibc 2.18)"
102 Further machine-dependent hints about processor capabilities.
103 .TP
104 .B AT_ICACHEBSIZE
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
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.
119 .TP
120 .B AT_L1D_CACHESIZE
121 The L1 data cache size.
122 .TP
123 .B AT_L1I_CACHEGEOMETRY
124 Geometry of the L1 instruction cache, encoded as for
125 .BR AT_L1D_CACHEGEOMETRY .
126 .TP
127 .B AT_L1I_CACHESIZE
128 The L1 instruction cache size.
129 .TP
130 .B AT_L2_CACHEGEOMETRY
131 Geometry of the L2 cache, encoded as for
132 .BR AT_L1D_CACHEGEOMETRY .
133 .TP
134 .B AT_L2_CACHESIZE
135 The L2 cache size.
136 .TP
137 .B AT_L3_CACHEGEOMETRY
138 Geometry of the L3 cache, encoded as for
139 .BR AT_L1D_CACHEGEOMETRY .
140 .TP
141 .B AT_L3_CACHESIZE
142 The L3 cache size.
143 .TP
144 .B AT_PAGESZ
145 The system page size (the same value returned by
146 .IR sysconf(_SC_PAGESIZE) ).
147 .TP
148 .B AT_PHDR
149 The address of the program headers of the executable.
150 .TP
151 .B AT_PHENT
152 The size of program header entry.
153 .TP
154 .B AT_PHNUM
155 The number of program headers.
156 .TP
157 .B AT_PLATFORM
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
161 .I rpath
162 values.
163 .TP
164 .B AT_RANDOM
165 The address of sixteen bytes containing a random value.
166 .TP
167 .B AT_SECURE
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)).
175 Alternatively,
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.
181 (See also
182 .BR secure_getenv (3).)
183 .TP
184 .B AT_SYSINFO
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).
187 .TP
188 .B AT_SYSINFO_EHDR
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.
192 .TP
193 .B AT_UCACHEBSIZE
194 The unified cache block size.
195 .TP
196 .B AT_UID
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
207 .TP
208 .BR ENOENT " (since glibc 2.19)"
209 .\" commit b9ab448f980e296eac21ac65f53783967cc6037b
210 No entry corresponding to
211 .I type
212 could be found in the auxiliary vector.
213 .SH ATTRIBUTES
214 For an explanation of the terms used in this section, see
215 .BR attributes (7).
216 .TS
217 allbox;
218 lbx lb lb
219 l l l.
220 Interface Attribute Value
221 T{
222 .na
223 .nh
224 .BR getauxval ()
225 T} Thread safety MT-Safe
226 .TE
227 .SH STANDARDS
228 GNU.
229 .SH HISTORY
230 glibc 2.16.
231 .SH NOTES
232 The primary consumer of the information in the auxiliary vector
233 is the dynamic linker,
234 .BR ld\-linux.so (8).
235 The auxiliary vector is a convenient and efficient shortcut
236 that allows the kernel to communicate a certain set of standard
237 information that the dynamic linker usually or always needs.
238 In some cases, the same information could be obtained by system calls,
239 but using the auxiliary vector is cheaper.
240 .P
241 The auxiliary vector resides just above the argument list and
242 environment in the process address space.
243 The auxiliary vector supplied to a program can be viewed by setting the
244 .B LD_SHOW_AUXV
245 environment variable when running a program:
246 .P
247 .in +4n
248 .EX
249 $ LD_SHOW_AUXV=1 sleep 1
250 .EE
251 .in
252 .P
253 The auxiliary vector of any process can (subject to file permissions)
254 be obtained via
255 .IR /proc/ pid /auxv ;
256 see
257 .BR proc (5)
258 for more information.
259 .SH BUGS
260 Before the addition of the
261 .B ENOENT
262 error in glibc 2.19,
263 there was no way to unambiguously distinguish the case where
264 .I type
265 could not be found from the case where the value corresponding to
266 .I type
267 was zero.
268 .SH SEE ALSO
269 .BR execve (2),
270 .BR secure_getenv (3),
271 .BR vdso (7),
272 .BR ld\-linux.so (8)