original/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 .\" FIXME glibc 2.18 added AT_HWCAP2, which needs to e documented
  28 .\"
  29 .TH GETAUXVAL 3  2014-08-19 "GNU" "Linux Programmer's Manual"
  30 .SH NAME
  31 getauxval \- retrieve a value from the auxiliary vector
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <sys/auxv.h>
  35 .sp
  36 .BI "unsigned long getauxval(unsigned long " type );
  37 .fi
  38 .SH DESCRIPTION
  39 The
  40 .BR getauxval ()
  41 function retrieves values from the auxiliary vector,
  42 a mechanism that the kernel's ELF binary loader
  43 uses to pass certain information to
  44 user space when a program is executed.
  45
  46 Each entry in the auxiliary vector consists of a pair of values:
  47 a type that identifies what this entry represents,
  48 and a value for that type.
  49 Given the argument
  50 .IR type ,
  51 .BR getauxval ()
  52 returns the corresponding value.
  53
  54 The value returned for each
  55 .I type
  56 is given in the following list.
  57 Not all
  58 .I type
  59 values are present on all architectures.
  60 .TP
  61 .BR AT_BASE
  62 The base address of the program interpreter (usually, the dynamic linker).
  63 .TP
  64 .BR AT_BASE_PLATFORM
  65 A string identifying the real platform; may differ from
  66 .BR AT_PLATFORM
  67 (PowerPC only).
  68 .TP
  69 .BR AT_CLKTCK
  70 The frequency with which
  71 .BR times (2)
  72 counts.
  73 This value can also be obtained via
  74 .IR sysconf(_SC_CLK_TCK) .
  75 .TP
  76 .BR AT_DCACHEBSIZE
  77 The data cache block size.
  78 .TP
  79 .BR AT_EGID
  80 The effective group ID of the thread.
  81 .TP
  82 .BR AT_ENTRY
  83 The entry address of the executable.
  84 .TP
  85 .BR AT_EUID
  86 The effective user ID of the thread.
  87 .TP
  88 .BR AT_EXECFD
  89 File descriptor of program.
  90 .TP
  91 .BR AT_EXECFN
  92 Pathname used to execute program.
  93 .TP
  94 .BR AT_FLAGS
  95 Flags (unused).
  96 .TP
  97 .BR AT_FPUCW
  98 Used FPU control word (SuperH architecture only).
  99 This gives some information about the FPU initialization
 100 performed by the kernel.
 101 .TP
 102 .BR AT_GID
 103 The real group ID of the thread.
 104 .TP
 105 .BR AT_HWCAP
 106 A pointer to a multibyte mask of bits whose settings
 107 indicate detailed processor capabilities.
 108 The contents of the bit mask are hardware dependent
 109 (for example, see the kernel source file
 110 .IR arch/x86/include/asm/cpufeature.h
 111 for details relating to the Intel x86 architecture).
 112 A human-readable version of the same information is available via
 113 .IR /proc/cpuinfo .
 114 .TP
 115 .BR AT_ICACHEBSIZE
 116 The instruction cache block size.
 117 .\" .TP
 118 .\" .BR AT_IGNORE
 119 .\" .TP
 120 .\" .BR AT_IGNOREPPC
 121 .\" .TP
 122 .\" .BR AT_NOTELF
 123 .TP
 124 .BR AT_PAGESZ
 125 The system page size (the same value returned by
 126 .IR sysconf(_SC_PAGESIZE) ).
 127 .TP
 128 .BR AT_PHDR
 129 The address of the program headers of the executable.
 130 .TP
 131 .BR AT_PHENT
 132 The size of program header entry.
 133 .TP
 134 .BR AT_PHNUM
 135 The number of program headers.
 136 .TP
 137 .BR AT_PLATFORM
 138 A pointer to a string that identifies the hardware platform
 139 that the program is running on.
 140 The dynamic linker uses this in the interpretation of
 141 .IR rpath
 142 values.
 143 .TP
 144 .BR AT_RANDOM
 145 The address of sixteen bytes containing a random value.
 146 .TP
 147 .BR AT_SECURE
 148 Has a nonzero value if this executable should be treated securely.
 149 Most commonly, a nonzero value indicates that the process is
 150 executing a set-user-ID or set-group-ID program; alternatively,
 151 a nonzero value may be triggered by a Linux Security Module.
 152 When this value is nonzero,
 153 the dynamic linker disables the use of certain environment variables (see
 154 .BR ld-linux.so (8))
 155 and glibc changes other aspects of its behavior.
 156 (See also
 157 .BR secure_getenv (3).)
 158 .TP
 159 .BR AT_SYSINFO
 160 The entry point to the system call function in the vDSO.
 161 Not present/needed on all architectures (e.g., absent on x86-64).
 162 .TP
 163 .BR AT_SYSINFO_EHDR
 164 The address of a page containing the virtual Dynamic Shared Object (vDSO)
 165 that the kernel creates in order to provide fast implementations of
 166 certain system calls.
 167 .TP
 168 .BR AT_UCACHEBSIZE
 169 The unified cache block size.
 170 .TP
 171 .BR AT_UID
 172 The real user ID of the thread.
 173 .SH RETURN VALUE
 174 On success,
 175 .BR getauxval ()
 176 returns the value corresponding to
 177 .IR type .
 178 If
 179 .I type
 180 is not found, 0 is returned.
 181 .SH ERRORS
 182 .TP
 183 .BR ENOENT " (since glibc 2.19)"
 184 .\" commit b9ab448f980e296eac21ac65f53783967cc6037b
 185 No entry corresponding to
 186 .IR type
 187 could be found in the auxiliary vector.
 188 .SH VERSIONS
 189 The
 190 .BR getauxval ()
 191 function was added to glibc in version 2.16.
 192 .SH ATTRIBUTES
 193 .SS Multithreading (see pthreads(7))
 194 The
 195 .BR getauxval ()
 196 function is thread-safe.
 197 .SH CONFORMING TO
 198 This function is a nonstandard glibc extension.
 199 .SH NOTES
 200 The primary consumer of the information in the auxiliary vector
 201 is the dynamic linker
 202 .BR ld-linux.so (8).
 203 The auxiliary vector is a convenient and efficient shortcut
 204 that allows the kernel to communicate a certain set of standard
 205 information that the dynamic linker usually or always needs.
 206 In some cases, the same information could be obtained by system calls,
 207 but using the auxiliary vector is cheaper.
 208
 209 The auxiliary vector resides just above the argument list and
 210 environment in the process address space.
 211 The auxiliary vector supplied to a program can be viewed by setting the
 212 .B LD_SHOW_AUXV
 213 environment variable when running a program:
 214
 215     $ LD_SHOW_AUXV=1 sleep 1
 216
 217 The auxiliary vector of any process can (subject to file permissions)
 218 be obtained via
 219 .IR /proc/PID/auxv ;
 220 see
 221 .BR proc (5)
 222 for more information.
 223 .SH BUGS
 224 Before the addition of the
 225 .B ENOENT
 226 error in glibc 2.19,
 227 there was no way to unambiguously distinguish the case where
 228 .I type
 229 could not be found from the case where the value corresponding to
 230 .I type
 231 was zer0.
 232 .SH SEE ALSO
 233 .BR secure_getenv (3),
 234 .BR vdso (7),
 235 .BR ld-linux.so (8)
 236 .SH COLOPHON
 237 This page is part of release 3.79 of the Linux
 238 .I man-pages
 239 project.
 240 A description of the project,
 241 information about reporting bugs,
 242 and the latest version of this page,
 243 can be found at
 244 \%http://www.kernel.org/doc/man\-pages/.