=========================================================================== Libauxv The "Auxiliary Vector Library" User & Developer Guide For the GNU/Linux OS Contributed by IBM Corporation Copyright (C) 2010, 2011 IBM Corporation
=========================================================================== Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the file entitled "GFDLv1.3.txt"
=========================================================================== NOTE:Eight space tabs are the optimum editor setting for reading this file.
Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
Date Created: January 29, 2010
Last Updated: Mar 20, 2011
===========================================================================
Table of Contents:
1. Introduction
1.1. Rationale
2. License
3. Supported Platforms
4. Dependencies
4.1 GNU/Linux OS
4.2 GLIBC Minimum Version
5. Configuration
6. Make Rules
7. Use
8. Contributing
A. History
B. Acknowledgements
- Introduction
1.1. Rationale
The functionality in Libauxv was originally proposed for GLIBC but was rejected:
http://sources.redhat.com/ml/libc-alpha/2006-01/msg00051.html
The reason this library is necessary is as follows:
1.) GLIBC won't provide access to the 5th process variable, which is the auxiliary vector (see the link above).
2.) Libraries may need access to the auxv information but only 'main' can find it.
3.) Libraries may try to find the auxv after the env, but as a library you can't guarantee that a user application hasn't mangled the environment.
4.) Given that the most reliable method for querying the aux vector is through /proc/self/auxv a reusable library is useful.
5.) There is an automatic fallback to attempting to read the aux vector from the env if the /proc/self/auxv isn't supported by the kernel.
- License
Libauxv is released under the "New BSD License" as indicated by the file COPYING.txt.
- Supported Platforms
Currently Libauxv has only been tested on the Power Architecture POWER platforms. The maintainer will accept patches for other architectures. The principle should work for other architectures and platforms.
- Dependencies
4.1 GNU/Linux OS
Libauxv is designed to query /proc/self/auxv for the auxiliary vector. Sufficiently old kernels may not have support for this. In this case Libauxv will attempt to use a fallback mechanism and locate the auxiliary vector in the process environment.
4.2 GLIBC Minimum Version
Applications which intend to use libauxv must link against libpthread.so (-lpthread) because libauxv uses pthread_once () to enforce threadsafe singleton creation. This of course requires a version of glibc with NPTL support (GLIBC 2.5)
- Configuration
Libauxv must be built in a directory that is not the base level source directory.
CC=/opt/at4.0/bin/gcc CFLAGS="-m32 -g -O2" ../libauxv/configure
--build=powerpc-linux --host=powerpc-linux --enable-shared
--enable-static 2>&1 | tee _configure32
CC=/opt/at4.0/bin/gcc CFLAGS="-m64 -g -O2" ../libauxv/configure
--build=powerpc64-linux --host=powerpc64-linux --enable-shared
--enable-static 2>&1 | tee _configure64
- Make Rules
make all: Build libauxv-X.Y.Z.so, libauxv.so, libauxv.so.1, and lsauxv.
make check: The libauxv test suite tests the primary auxv fetching method as well as the fallback method. In order to test the fallback method a version of the library is built which globalizes the __auxv_fallback symbol. This is libauxv_test-0.0.9.so, libauxv_test.so, and libauxv_test.so.1. These libraries never get installed.
make install: Results in the installation of libauxv-X.Y.Z.so, libauxv.so, libauxv.so.1 into @libdir@ as specified by configure.
Results in the installation of lsauxv into @bindir@ as specified by
configure.
Results in the installation of <auxv/auxv.h> and <auxv/hwcap.h> into the
@includedir@ specified by configure.
Results in the installation of man/auxv.3 and man/lsauxv.1 into @mandir@
as specified by configure. Also results in the creation of man/lsauxv.3
which points to man/auxv.3
install_root=<new_top_level>
This causes the aforementioned libraries, applications, and header files
to be installed into <new_top_level>/@libdir@ <new_top_level>/@bindir@,
<new_top_level>/@includedir@, and <new_top_level>/@mandir@
make uninstall: Results in all installed files being removed.
make install-headers: Results in the installation of <auxv/auxv.h> and <auxv/hwcap.h> into the @includedir@ specified by configure.
- Use
It should be noted that use of Libauxv will most likely result in the mapping of a page of memorty that is not able to be reclaimed or freed until the parent process exits.
For information on how to use the facilities provided by Libauxv please read the man pages auxv.3 and lsauxv.c included with this source code.
- Contributing
We simply ask that you contribute modifications back to the community as a gesture of goodwill.
In order to contribute as an individual please fill out the ICLA.txt file, sign, date, scan, and email to the maintainer.
In order to contribute as a corporate entit please fill out the CCLA.txt file, sign, date, scan, and email to the maintainer.
Individual contributions should use the signed-off method as indicated in the CONTRIBUTIONS file.
A. History
-
Libauxv was originally written and packaged by Sean Curry spcurry5@linux.vnet.ibm.com
-
It was modified for performance by Steve Munroe munroesj@us.ibm.com
-
It was updated for breadth and packaged for community consumption by Ryan S. Arnold rsa@us.ibm.com