Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 273 insertions, 0 deletions

diff --git a/man3/getauxval.3 b/man3/getauxval.3
new file mode 100644
index 0000000..8e7d5e4
--- /dev/null
+++ b/man3/getauxval.3
@@ -0,0 +1,273 @@
+'\" t
+.\" Copyright 2012 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" See also https://lwn.net/Articles/519085/
+.\"
+.TH getauxval 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+getauxval \- retrieve a value from the auxiliary vector
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/auxv.h>
+.PP
+.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.
+.PP
+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.
+.PP
+The value returned for each
+.I type
+is given in the following list.
+Not all
+.I type
+values are present on all architectures.
+.TP
+.B AT_BASE
+The base address of the program interpreter (usually, the dynamic linker).
+.TP
+.B AT_BASE_PLATFORM
+A pointer to a string (PowerPC and MIPS only).
+On PowerPC, this identifies the real platform; may differ from
+.BR AT_PLATFORM "."
+On MIPS,
+.\" commit e585b768da111f2c2d413de6214e83bbdfee8f22
+this identifies the ISA level (since Linux 5.7).
+.TP
+.B AT_CLKTCK
+The frequency with which
+.BR times (2)
+counts.
+This value can also be obtained via
+.IR sysconf(_SC_CLK_TCK) .
+.TP
+.B AT_DCACHEBSIZE
+The data cache block size.
+.TP
+.B AT_EGID
+The effective group ID of the thread.
+.TP
+.B AT_ENTRY
+The entry address of the executable.
+.TP
+.B AT_EUID
+The effective user ID of the thread.
+.TP
+.B AT_EXECFD
+File descriptor of program.
+.TP
+.B AT_EXECFN
+A pointer to a string containing the pathname used to execute the program.
+.TP
+.B AT_FLAGS
+Flags (unused).
+.TP
+.B AT_FPUCW
+Used FPU control word (SuperH architecture only).
+This gives some information about the FPU initialization
+performed by the kernel.
+.TP
+.B AT_GID
+The real group ID of the thread.
+.TP
+.B AT_HWCAP
+An architecture and ABI dependent bit-mask whose settings
+indicate detailed processor capabilities.
+The contents of the bit mask are hardware dependent
+(for example, see the kernel source file
+.I arch/x86/include/asm/cpufeature.h
+for details relating to the Intel x86 architecture; the value
+returned is the first 32-bit word of the array described there).
+A human-readable version of the same information is available via
+.IR /proc/cpuinfo .
+.TP
+.BR AT_HWCAP2 " (since glibc 2.18)"
+Further machine-dependent hints about processor capabilities.
+.TP
+.B AT_ICACHEBSIZE
+The instruction cache block size.
+.\" .TP
+.\" .BR AT_IGNORE
+.\" .TP
+.\" .BR AT_IGNOREPPC
+.\" .TP
+.\" .BR AT_NOTELF
+.TP
+.\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147
+.B AT_L1D_CACHEGEOMETRY
+Geometry of the L1 data cache, encoded with the cache line size in bytes
+in the bottom 16 bits and the cache associativity in the next 16 bits.
+The associativity is such that if N is the 16-bit value,
+the cache is N-way set associative.
+.TP
+.B AT_L1D_CACHESIZE
+The L1 data cache size.
+.TP
+.B AT_L1I_CACHEGEOMETRY
+Geometry of the L1 instruction cache, encoded as for
+.BR AT_L1D_CACHEGEOMETRY .
+.TP
+.B AT_L1I_CACHESIZE
+The L1 instruction cache size.
+.TP
+.B AT_L2_CACHEGEOMETRY
+Geometry of the L2 cache, encoded as for
+.BR AT_L1D_CACHEGEOMETRY .
+.TP
+.B AT_L2_CACHESIZE
+The L2 cache size.
+.TP
+.B AT_L3_CACHEGEOMETRY
+Geometry of the L3 cache, encoded as for
+.BR AT_L1D_CACHEGEOMETRY .
+.TP
+.B AT_L3_CACHESIZE
+The L3 cache size.
+.TP
+.B AT_PAGESZ
+The system page size (the same value returned by
+.IR sysconf(_SC_PAGESIZE) ).
+.TP
+.B AT_PHDR
+The address of the program headers of the executable.
+.TP
+.B AT_PHENT
+The size of program header entry.
+.TP
+.B AT_PHNUM
+The number of program headers.
+.TP
+.B 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
+.I rpath
+values.
+.TP
+.B AT_RANDOM
+The address of sixteen bytes containing a random value.
+.TP
+.B 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 binary
+(so that its real and effective UIDs or GIDs differ from one another),
+or that it gained capabilities by executing
+a binary file that has capabilities (see
+.BR capabilities (7)).
+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
+.B 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
+.B 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
+.B AT_UCACHEBSIZE
+The unified cache block size.
+.TP
+.B 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
+.TP
+.BR ENOENT " (since glibc 2.19)"
+.\" commit b9ab448f980e296eac21ac65f53783967cc6037b
+No entry corresponding to
+.I type
+could be found in the auxiliary vector.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getauxval ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+GNU.
+.SH HISTORY
+glibc 2.16.
+.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.
+.PP
+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:
+.PP
+.in +4n
+.EX
+$ LD_SHOW_AUXV=1 sleep 1
+.EE
+.in
+.PP
+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 BUGS
+Before the addition of the
+.B ENOENT
+error in glibc 2.19,
+there was no way to unambiguously distinguish the case where
+.I type
+could not be found from the case where the value corresponding to
+.I type
+was zero.
+.SH SEE ALSO
+.BR execve (2),
+.BR secure_getenv (3),
+.BR vdso (7),
+.BR ld\-linux.so (8)