man3/getauxval.3

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