man3/getauxval.3

   1 .\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   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.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" See also https://lwn.net/Articles/519085/
  26 .\"
  27 .TH GETAUXVAL 3  2019-10-10 "GNU" "Linux Programmer's Manual"
  28 .SH NAME
  29 getauxval \- retrieve a value from the auxiliary vector
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sys/auxv.h>
  33 .PP
  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.
  43 .PP
  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.
  51 .PP
  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 pointer to a string identifying the real platform; may differ from
  64 .BR AT_PLATFORM
  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 A pointer to a string containing the pathname used to execute the program.
  91 .TP
  92 .BR AT_FLAGS
  93 Flags (unused).
  94 .TP
  95 .BR AT_FPUCW
  96 Used FPU control word (SuperH architecture only).
  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
 104 An architecture and ABI dependent bit-mask whose settings
 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
 109 for details relating to the Intel x86 architecture; the value
 110 returned is the first 32-bit word of the array described there).
 111 A human-readable version of the same information is available via
 112 .IR /proc/cpuinfo .
 113 .TP
 114 .BR AT_HWCAP2 " (since glibc 2.18)"
 115 Further machine-dependent hints about processor capabilities.
 116 .TP
 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 .\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147
 127 .BR AT_L1D_CACHEGEOMETRY
 128 Geometry of the L1 data cache, encoded with the cache line size in bytes
 129 in the bottom 16 bits and the cache associativity in the next 16 bits.
 130 The associativity is such that if N is the 16-bit value,
 131 the cache is N-way set associative.
 132 .TP
 133 .BR AT_L1D_CACHESIZE
 134 The L1 data cache size.
 135 .TP
 136 .BR AT_L1I_CACHEGEOMETRY
 137 Geometry of the L1 instruction cache, encoded as for
 138 .BR AT_L1D_CACHEGEOMETRY .
 139 .TP
 140 .BR AT_L1I_CACHESIZE
 141 The L1 instruction cache size.
 142 .TP
 143 .BR AT_L2_CACHEGEOMETRY
 144 Geometry of the L2 cache, encoded as for
 145 .BR AT_L1D_CACHEGEOMETRY .
 146 .TP
 147 .BR AT_L2_CACHESIZE
 148 The L2 cache size.
 149 .TP
 150 .BR AT_L3_CACHEGEOMETRY
 151 Geometry of the L3 cache, encoded as for
 152 .BR AT_L1D_CACHEGEOMETRY .
 153 .TP
 154 .BR AT_L3_CACHESIZE
 155 The L3 cache size.
 156 .TP
 157 .BR AT_PAGESZ
 158 The system page size (the same value returned by
 159 .IR sysconf(_SC_PAGESIZE) ).
 160 .TP
 161 .BR AT_PHDR
 162 The address of the program headers of the executable.
 163 .TP
 164 .BR AT_PHENT
 165 The size of program header entry.
 166 .TP
 167 .BR AT_PHNUM
 168 The number of program headers.
 169 .TP
 170 .BR AT_PLATFORM
 171 A pointer to a string that identifies the hardware platform
 172 that the program is running on.
 173 The dynamic linker uses this in the interpretation of
 174 .IR rpath
 175 values.
 176 .TP
 177 .BR AT_RANDOM
 178 The address of sixteen bytes containing a random value.
 179 .TP
 180 .BR AT_SECURE
 181 Has a nonzero value if this executable should be treated securely.
 182 Most commonly, a nonzero value indicates that the process is
 183 executing a set-user-ID or set-group-ID binary
 184 (so that its real and effective UIDs or GIDs differ from one another),
 185 or that it gained capabilities by executing
 186 a binary file that has capabilities (see
 187 .BR capabilities (7)).
 188 Alternatively,
 189 a nonzero value may be triggered by a Linux Security Module.
 190 When this value is nonzero,
 191 the dynamic linker disables the use of certain environment variables (see
 192 .BR ld-linux.so (8))
 193 and glibc changes other aspects of its behavior.
 194 (See also
 195 .BR secure_getenv (3).)
 196 .TP
 197 .BR AT_SYSINFO
 198 The entry point to the system call function in the vDSO.
 199 Not present/needed on all architectures (e.g., absent on x86-64).
 200 .TP
 201 .BR AT_SYSINFO_EHDR
 202 The address of a page containing the virtual Dynamic Shared Object (vDSO)
 203 that the kernel creates in order to provide fast implementations of
 204 certain system calls.
 205 .TP
 206 .BR AT_UCACHEBSIZE
 207 The unified cache block size.
 208 .TP
 209 .BR AT_UID
 210 The real user ID of the thread.
 211 .SH RETURN VALUE
 212 On success,
 213 .BR getauxval ()
 214 returns the value corresponding to
 215 .IR type .
 216 If
 217 .I type
 218 is not found, 0 is returned.
 219 .SH ERRORS
 220 .TP
 221 .BR ENOENT " (since glibc 2.19)"
 222 .\" commit b9ab448f980e296eac21ac65f53783967cc6037b
 223 No entry corresponding to
 224 .IR type
 225 could be found in the auxiliary vector.
 226 .SH VERSIONS
 227 The
 228 .BR getauxval ()
 229 function was added to glibc in version 2.16.
 230 .SH ATTRIBUTES
 231 For an explanation of the terms used in this section, see
 232 .BR attributes (7).
 233 .TS
 234 allbox;
 235 lb lb lb
 236 l l l.
 237 Interface       Attribute       Value
 238 T{
 239 .BR getauxval ()
 240 T}      Thread safety   MT-Safe
 241 .TE
 242 .SH CONFORMING TO
 243 This function is a nonstandard glibc extension.
 244 .SH NOTES
 245 The primary consumer of the information in the auxiliary vector
 246 is the dynamic linker,
 247 .BR ld-linux.so (8).
 248 The auxiliary vector is a convenient and efficient shortcut
 249 that allows the kernel to communicate a certain set of standard
 250 information that the dynamic linker usually or always needs.
 251 In some cases, the same information could be obtained by system calls,
 252 but using the auxiliary vector is cheaper.
 253 .PP
 254 The auxiliary vector resides just above the argument list and
 255 environment in the process address space.
 256 The auxiliary vector supplied to a program can be viewed by setting the
 257 .B LD_SHOW_AUXV
 258 environment variable when running a program:
 259 .PP
 260 .in +4n
 261 .EX
 262 $ LD_SHOW_AUXV=1 sleep 1
 263 .EE
 264 .in
 265 .PP
 266 The auxiliary vector of any process can (subject to file permissions)
 267 be obtained via
 268 .IR /proc/[pid]/auxv ;
 269 see
 270 .BR proc (5)
 271 for more information.
 272 .SH BUGS
 273 Before the addition of the
 274 .B ENOENT
 275 error in glibc 2.19,
 276 there was no way to unambiguously distinguish the case where
 277 .I type
 278 could not be found from the case where the value corresponding to
 279 .I type
 280 was zero.
 281 .SH SEE ALSO
 282 .BR secure_getenv (3),
 283 .BR vdso (7),
 284 .BR ld-linux.so (8)