getauxval.3: Document getauxval() function added in glibc 2.16

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 214 insertions, 0 deletions

diff --git a/man3/getauxval.3 b/man3/getauxval.3
new file mode 100755
index 0000000000..5120f9ac8b
--- /dev/null
+++ b/man3/getauxval.3
@@ -0,0 +1,214 @@
+.\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" 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 <sys/auxv.h>
+.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