hlibc
hlibc is a freestanding libc that implements a subset of the POSIX, C99
and C11 hosted implementation requirements. The mathematics library is
a minimalistic fork of Sun fdlibm focused on IEEE-754-2008 floating
point research and the study of fdlibm's core components. The normative
case of IEEE-754-2008 floats 'f' are correctly printed and rounded.
hlibc is targeted at POSIX systems and currently works with the Linux
kernel's syscall ABI on the i386. x86_64 and aarch64 architectures.
FreeBSD and OpenBSD are supported on an experimental level.
hlibc focuses primarily on algorithmic correctness and effectiveness
for the sake of educational purposes. Unlike many smaller libcs, hlibc
has correct getc/putc semantics which are designed to eliminate short
reads and writes. These getc/putc semantics lie at the heart of a libc's
stdio and canonically define a majority of its usefulness. Indeed, no
programming language has ever succeeded in completely replacing C's
stdio functionalities with a shorter, more concise or more effective
interface.
Because hlibc does not need to be installed in order to be used, it is
well suited for academic study as a tool for understanding how more
complex libc work.
As much as possible, linux and glibc specific functionalities are
excluded from hlibc. Instead, hlibc focuses on supplying functions
which are described in the POSIX, C99 and C11 standards.
hlibc was originally authored by CM Graff. Along the way many people
have contributed code, all of whom are listed in the LICENSE and the
files they authored hold their copyrights.
BUILDING:
---------
hlibc creates a wrapper for gcc or clang named "compiler" which
redirects linking options allowing hlibc to be installed and used
without root privilege.
Building on Linux:
git clone https://github.com/hlibc/hlibc
cd hlibc
./configure --prefix=/home/$USER/buildarea
make
make install
/home/$USER/buildarea/bin/compiler hello.c
If all went as expected then `compiler' will link against hlibc's
libc.a and header files, completely excluding those of the host. Run
`readelf -a' on the resulting binary and inspect the output to ensure
that it was not contaminated by the host libc.
Building on FreeBSD:
pkg install gcc git
git clone https://github.com/hlibc/hlibc
cd hlibc
CC=gcc ./configure --prefix=/home/$USER/buildarea
gmake
gmake install
FreeBSD support is still experimental. Currently, only the gcc compiler
wrapper is working correctly. Clang does work, but for whatever reason
the compiler wrapper logic is broken. If you choose to use clang then
the libc.a and the crt*.o files must be linked in by hand. Freebsd
binaries may need to be "branded". This is the case at least for
aarch64, but not x86_64. They can be branded with the following command:
brandelf -t freebsd <filename>
Building on OpenBSD:
git clone https://github.com/hlibc/hlibc
cd hlibc
CC=clang ./configure --prefix=/home/$USER/buildarea
gmake
gmake install
OpenBSD support is still in its early stages. At this time gcc is not
working however llvm/clang is working fine. OpenBSD is purportedly
switching its focus to llvm/clang and will not likely be updating gcc
support. For this reason, it's advisable to simply use clang instead of
gcc when building hlibc on OpenBSD.
Note on BSDs:
BSDs have the tendency to require that ELF binaries contain
"notes" or "branding". There is of course no standardized way
to handle this. I have provided some instructions and tested
against various workarounds. If you want to primarily develop
hlibc on a BSD variant then it would be prudent to create some
automatic methods for handling these "notes" or "branding". At
this time, it seems like it would needlessly inflate the hlibc
code base to carry code and methods for handling all of the
various permutations needed by the BSDs.
MATHEMATICAL CORRECTNESS:
------------------------
hlibc pays careful attention to mathematics boundaries. A series of
safe arithmetic functions have been devised which use the inverse
properties of the arithmetic operators in order to provide checks which
can catch and respond to arithmetic overflows before they happen. These
functions borrow from the concept of saturation arithmetic but extend
its principles to be useful in a production environment where a
saturation boundary is not acceptable.
TESTING:
--------
To download, build and run the hlibc-test test suite invoke:
make test
hlibc-test was split off from hlibc as it started to grow larger. It is
retrieved automatically when `make test' is invoked. If for some reason
you want it separately it can be downloaded from:
https://github.com/hlibc/hlibc-test
hlibc-test also contains the utility suite `hbox' which has several
standalone tools such as `ls', `cp' and et cetera. hbox is not actively
developed at this time and is mostly used to test hlibc.
REVISION CONTROL:
-----------------
https://github.com/hlibc/hlibc
KNOWN BUGS:
-----------
The fcsanf family is under construction at this time. Though it can be
linked in, it should not be used until this notice is removed.
CONTACT:
--------
[email protected]
COPYING:
--------
Please see the attached LICENSE file for the list of contributors and
copying details.
SPONSORS:
---------
Packet WorkOnArm (hardware and CI)
The GCC server farm (hardware)
Adrian Parvin D. Ouano (domain hosting)
Janne Johansson (hardware)
Thank you to everyone who has helped hlibc become a reality. I could
not have done it without your help, guidance and comradarie.
USEFUL LINKS:
-------------
Information about the syscall layers of various OS
https://john-millikin.com/unix-syscalls
ROADMAP:
-------
ftell and clearerr for GNU sed-3.01
sysconf for GNU grep-2.4
ftell, fseek, longjmp and setjmp for tcc (and probably others)
finish the scanf family