]>
Commit | Line | Data |
---|---|---|
4946106c MK |
1 | .\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
4946106c MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
4946106c MK |
24 | .\" |
25 | .\" See also https://lwn.net/Articles/519085/ | |
26 | .\" | |
4b8c67d9 | 27 | .TH GETAUXVAL 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
4946106c MK |
28 | .SH NAME |
29 | getauxval \- retrieve a value from the auxiliary vector | |
30 | .SH SYNOPSIS | |
31 | .nf | |
32 | .B #include <sys/auxv.h> | |
68e4db0a | 33 | .PP |
4946106c MK |
34 | .BI "unsigned long getauxval(unsigned long " type ); |
35 | .fi | |
36 | .SH DESCRIPTION | |
37 | The | |
38 | .BR getauxval () | |
39 | function retrieves values from the auxiliary vector, | |
40 | a mechanism that the kernel's ELF binary loader | |
41 | uses to pass certain information to | |
42 | user space when a program is executed. | |
847e0d88 | 43 | .PP |
4946106c MK |
44 | Each entry in the auxiliary vector consists of a pair of values: |
45 | a type that identifies what this entry represents, | |
46 | and a value for that type. | |
47 | Given the argument | |
48 | .IR type , | |
49 | .BR getauxval () | |
50 | returns the corresponding value. | |
847e0d88 | 51 | .PP |
4946106c MK |
52 | The value returned for each |
53 | .I type | |
54 | is given in the following list. | |
55 | Not all | |
56 | .I type | |
57 | values are present on all architectures. | |
58 | .TP | |
59 | .BR AT_BASE | |
60 | The base address of the program interpreter (usually, the dynamic linker). | |
61 | .TP | |
62 | .BR AT_BASE_PLATFORM | |
63 | A string identifying the real platform; may differ from | |
fa1d2749 | 64 | .BR AT_PLATFORM |
4946106c MK |
65 | (PowerPC only). |
66 | .TP | |
67 | .BR AT_CLKTCK | |
68 | The frequency with which | |
69 | .BR times (2) | |
70 | counts. | |
71 | This value can also be obtained via | |
72 | .IR sysconf(_SC_CLK_TCK) . | |
73 | .TP | |
74 | .BR AT_DCACHEBSIZE | |
75 | The data cache block size. | |
76 | .TP | |
77 | .BR AT_EGID | |
78 | The effective group ID of the thread. | |
79 | .TP | |
80 | .BR AT_ENTRY | |
81 | The entry address of the executable. | |
82 | .TP | |
83 | .BR AT_EUID | |
84 | The effective user ID of the thread. | |
85 | .TP | |
86 | .BR AT_EXECFD | |
87 | File descriptor of program. | |
88 | .TP | |
89 | .BR AT_EXECFN | |
90 | Pathname used to execute program. | |
91 | .TP | |
92 | .BR AT_FLAGS | |
93 | Flags (unused). | |
94 | .TP | |
95 | .BR AT_FPUCW | |
fa1d2749 | 96 | Used FPU control word (SuperH architecture only). |
4946106c MK |
97 | This gives some information about the FPU initialization |
98 | performed by the kernel. | |
99 | .TP | |
100 | .BR AT_GID | |
101 | The real group ID of the thread. | |
102 | .TP | |
103 | .BR AT_HWCAP | |
7e318d44 | 104 | An architecture and ABI dependent bit-mask whose settings |
4946106c MK |
105 | indicate detailed processor capabilities. |
106 | The contents of the bit mask are hardware dependent | |
107 | (for example, see the kernel source file | |
108 | .IR arch/x86/include/asm/cpufeature.h | |
063bf5a7 | 109 | for details relating to the Intel x86 architecture; the value |
291415ef | 110 | returned is the first 32-bit word of the array described there). |
4946106c MK |
111 | A human-readable version of the same information is available via |
112 | .IR /proc/cpuinfo . | |
113 | .TP | |
2e380e89 MK |
114 | .BR AT_HWCAP2 " (since glibc 2.18)" |
115 | Further machine-dependent hints about processor capabilities. | |
116 | .TP | |
4946106c MK |
117 | .BR AT_ICACHEBSIZE |
118 | The instruction cache block size. | |
119 | .\" .TP | |
120 | .\" .BR AT_IGNORE | |
121 | .\" .TP | |
122 | .\" .BR AT_IGNOREPPC | |
123 | .\" .TP | |
124 | .\" .BR AT_NOTELF | |
125 | .TP | |
126 | .BR AT_PAGESZ | |
127 | The system page size (the same value returned by | |
1e4a9e18 | 128 | .IR sysconf(_SC_PAGESIZE) ). |
4946106c MK |
129 | .TP |
130 | .BR AT_PHDR | |
131 | The address of the program headers of the executable. | |
132 | .TP | |
133 | .BR AT_PHENT | |
134 | The size of program header entry. | |
135 | .TP | |
136 | .BR AT_PHNUM | |
137 | The number of program headers. | |
138 | .TP | |
139 | .BR AT_PLATFORM | |
140 | A pointer to a string that identifies the hardware platform | |
141 | that the program is running on. | |
142 | The dynamic linker uses this in the interpretation of | |
143 | .IR rpath | |
144 | values. | |
145 | .TP | |
146 | .BR AT_RANDOM | |
147 | The address of sixteen bytes containing a random value. | |
148 | .TP | |
149 | .BR AT_SECURE | |
150 | Has a nonzero value if this executable should be treated securely. | |
151 | Most commonly, a nonzero value indicates that the process is | |
422dd47f | 152 | executing a set-user-ID or set-group-ID binary |
36f99b92 | 153 | (so that its real and effective UIDs or GIDs differ from one another), |
422dd47f MK |
154 | or that it gained capabilities by executing |
155 | a binary file that has capabilities (see | |
6912d54f MK |
156 | .BR capabilities (7)). |
157 | Alternatively, | |
4946106c MK |
158 | a nonzero value may be triggered by a Linux Security Module. |
159 | When this value is nonzero, | |
160 | the dynamic linker disables the use of certain environment variables (see | |
161 | .BR ld-linux.so (8)) | |
fa1d2749 | 162 | and glibc changes other aspects of its behavior. |
4946106c MK |
163 | (See also |
164 | .BR secure_getenv (3).) | |
165 | .TP | |
166 | .BR AT_SYSINFO | |
5d4708c3 | 167 | The entry point to the system call function in the vDSO. |
4946106c MK |
168 | Not present/needed on all architectures (e.g., absent on x86-64). |
169 | .TP | |
170 | .BR AT_SYSINFO_EHDR | |
5d4708c3 | 171 | The address of a page containing the virtual Dynamic Shared Object (vDSO) |
4946106c MK |
172 | that the kernel creates in order to provide fast implementations of |
173 | certain system calls. | |
174 | .TP | |
175 | .BR AT_UCACHEBSIZE | |
176 | The unified cache block size. | |
177 | .TP | |
178 | .BR AT_UID | |
179 | The real user ID of the thread. | |
180 | .SH RETURN VALUE | |
181 | On success, | |
182 | .BR getauxval () | |
183 | returns the value corresponding to | |
184 | .IR type . | |
185 | If | |
186 | .I type | |
187 | is not found, 0 is returned. | |
188 | .SH ERRORS | |
89c1cb59 MK |
189 | .TP |
190 | .BR ENOENT " (since glibc 2.19)" | |
191 | .\" commit b9ab448f980e296eac21ac65f53783967cc6037b | |
192 | No entry corresponding to | |
193 | .IR type | |
194 | could be found in the auxiliary vector. | |
4946106c MK |
195 | .SH VERSIONS |
196 | The | |
197 | .BR getauxval () | |
198 | function was added to glibc in version 2.16. | |
b727421c | 199 | .SH ATTRIBUTES |
8c5731ff MK |
200 | For an explanation of the terms used in this section, see |
201 | .BR attributes (7). | |
202 | .TS | |
203 | allbox; | |
204 | lb lb lb | |
205 | l l l. | |
206 | Interface Attribute Value | |
207 | T{ | |
b727421c | 208 | .BR getauxval () |
8c5731ff MK |
209 | T} Thread safety MT-Safe |
210 | .TE | |
47297adb | 211 | .SH CONFORMING TO |
4946106c MK |
212 | This function is a nonstandard glibc extension. |
213 | .SH NOTES | |
214 | The primary consumer of the information in the auxiliary vector | |
215 | is the dynamic linker | |
216 | .BR ld-linux.so (8). | |
217 | The auxiliary vector is a convenient and efficient shortcut | |
218 | that allows the kernel to communicate a certain set of standard | |
219 | information that the dynamic linker usually or always needs. | |
220 | In some cases, the same information could be obtained by system calls, | |
221 | but using the auxiliary vector is cheaper. | |
847e0d88 | 222 | .PP |
4946106c MK |
223 | The auxiliary vector resides just above the argument list and |
224 | environment in the process address space. | |
225 | The auxiliary vector supplied to a program can be viewed by setting the | |
226 | .B LD_SHOW_AUXV | |
227 | environment variable when running a program: | |
019d9ee8 MK |
228 | .PP |
229 | .in +4n | |
230 | .EX | |
231 | $ LD_SHOW_AUXV=1 sleep 1 | |
232 | .EE | |
233 | .in | |
234 | .PP | |
4946106c MK |
235 | The auxiliary vector of any process can (subject to file permissions) |
236 | be obtained via | |
750653a8 | 237 | .IR /proc/[pid]/auxv ; |
4946106c MK |
238 | see |
239 | .BR proc (5) | |
240 | for more information. | |
89c1cb59 MK |
241 | .SH BUGS |
242 | Before the addition of the | |
243 | .B ENOENT | |
244 | error in glibc 2.19, | |
245 | there was no way to unambiguously distinguish the case where | |
246 | .I type | |
247 | could not be found from the case where the value corresponding to | |
248 | .I type | |
a03a7435 | 249 | was zero. |
47297adb | 250 | .SH SEE ALSO |
4946106c | 251 | .BR secure_getenv (3), |
951ae9c0 | 252 | .BR vdso (7), |
4946106c | 253 | .BR ld-linux.so (8) |