From 4946106cae7b024d3788e848a1c1b763ec58a6e1 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 7 Nov 2012 13:02:54 +0100 Subject: [PATCH] getauxval.3: Document getauxval() function added in glibc 2.16 Signed-off-by: Michael Kerrisk --- man3/getauxval.3 | 214 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100755 man3/getauxval.3 diff --git a/man3/getauxval.3 b/man3/getauxval.3 new file mode 100755 index 000000000..5120f9ac8 --- /dev/null +++ b/man3/getauxval.3 @@ -0,0 +1,214 @@ +.\" Copyright 2012 Michael Kerrisk +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" See also https://lwn.net/Articles/519085/ +.\" +.TH GETAUXVAL 3 2012-11-07 "GNU" "Linux Programmer's Manual" +.SH NAME +getauxval \- retrieve a value from the auxiliary vector +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "unsigned long getauxval(unsigned long " type ); +.fi +.SH DESCRIPTION +The +.BR getauxval () +function retrieves values from the auxiliary vector, +a mechanism that the kernel's ELF binary loader +uses to pass certain information to +user space when a program is executed. + +Each entry in the auxiliary vector consists of a pair of values: +a type that identifies what this entry represents, +and a value for that type. +Given the argument +.IR type , +.BR getauxval () +returns the corresponding value. + +The value returned for each +.I type +is given in the following list. +Not all +.I type +values are present on all architectures. +.TP +.BR AT_BASE +The base address of the program interpreter (usually, the dynamic linker). +.TP +.BR AT_BASE_PLATFORM +A string identifying the real platform; may differ from +.BR AT_PLATFORM +(PowerPC only). +.TP +.BR AT_CLKTCK +The frequency with which +.BR times (2) +counts. +This value can also be obtained via +.IR sysconf(_SC_CLK_TCK) . +.TP +.BR AT_DCACHEBSIZE +The data cache block size. +.TP +.BR AT_EGID +The effective group ID of the thread. +.TP +.BR AT_ENTRY +The entry address of the executable. +.TP +.BR AT_EUID +The effective user ID of the thread. +.TP +.BR AT_EXECFD +File descriptor of program. +.TP +.BR AT_EXECFN +Pathname used to execute program. +.TP +.BR AT_FLAGS +Flags (unused). +.TP +.BR AT_FPUCW +Used FPU control word (SuperH architecture only). +This gives some information about the FPU initialization +performed by the kernel. +.TP +.BR AT_GID +The real group ID of the thread. +.TP +.BR AT_HWCAP +A pointer to a multibyte mask of bits whose settings +indicate detailed processor capabilities. +The contents of the bit mask are hardware dependent +(for example, see the kernel source file +.IR arch/x86/include/asm/cpufeature.h +for details relating to the Intel x86 architecture). +A human-readable version of the same information is available via +.IR /proc/cpuinfo . +.TP +.BR AT_ICACHEBSIZE +The instruction cache block size. +.\" .TP +.\" .BR AT_IGNORE +.\" .TP +.\" .BR AT_IGNOREPPC +.\" .TP +.\" .BR AT_NOTELF +.TP +.BR AT_PAGESZ +The system page size (the same value returned by +.IR sysconf(_SC_PAGESIZE) . +.TP +.BR AT_PHDR +The address of the program headers of the executable. +.TP +.BR AT_PHENT +The size of program header entry. +.TP +.BR AT_PHNUM +The number of program headers. +.TP +.BR AT_PLATFORM +A pointer to a string that identifies the hardware platform +that the program is running on. +The dynamic linker uses this in the interpretation of +.IR rpath +values. +.TP +.BR AT_RANDOM +The address of sixteen bytes containing a random value. +.TP +.BR AT_SECURE +Has a nonzero value if this executable should be treated securely. +Most commonly, a nonzero value indicates that the process is +executing a set-user-ID or set-group-ID program; alternatively, +a nonzero value may be triggered by a Linux Security Module. +When this value is nonzero, +the dynamic linker disables the use of certain environment variables (see +.BR ld-linux.so (8)) +and glibc changes other aspects of its behavior. +(See also +.BR secure_getenv (3).) +.TP +.BR AT_SYSINFO +The entry point to the system call function in the VDSO. +Not present/needed on all architectures (e.g., absent on x86-64). +.TP +.BR AT_SYSINFO_EHDR +The address of a page containing the Virtual Dynamic Shared Object (VDSO) +that the kernel creates in order to provide fast implementations of +certain system calls. +.TP +.BR AT_UCACHEBSIZE +The unified cache block size. +.TP +.BR AT_UID +The real user ID of the thread. +.SH RETURN VALUE +On success, +.BR getauxval () +returns the value corresponding to +.IR type . +If +.I type +is not found, 0 is returned. +.SH ERRORS +No errors are diagnosed. +.SH VERSIONS +The +.BR getauxval () +function was added to glibc in version 2.16. +.SH "CONFORMING TO" +This function is a nonstandard glibc extension. +.SH NOTES +The primary consumer of the information in the auxiliary vector +is the dynamic linker +.BR ld-linux.so (8). +The auxiliary vector is a convenient and efficient shortcut +that allows the kernel to communicate a certain set of standard +information that the dynamic linker usually or always needs. +In some cases, the same information could be obtained by system calls, +but using the auxiliary vector is cheaper. + +The auxiliary vector resides just above the argument list and +environment in the process address space. +The auxiliary vector supplied to a program can be viewed by setting the +.B LD_SHOW_AUXV +environment variable when running a program: + + $ LD_SHOW_AUXV=1 sleep 1 + +The auxiliary vector of any process can (subject to file permissions) +be obtained via +.IR /proc/PID/auxv ; +see +.BR proc (5) +for more information. +.SH "SEE ALSO" +.BR secure_getenv (3), +.BR ld-linux.so (8) + +The kernel source file +.IR Documentation/ABI/stable/vdso