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