.pp
The C library includes the standard mathematical functions, character
string functions, and I/O functions.  The functions specified in Kernighan
and Ritchie have their arguments as given there, other functions are as defined
in UNIX.  This library assumes the existence of a simple UNIX-subset system call
interface, which is described below.  If you have a UNIX system or a UNIX look
alike, this code can be used as is.  If your system looks nothing like UNIX
you will have to write a few simple functions in C or assembly to implement
the UNIX-subset.  Also included is code for a very simple UNIX-subset which
which works with a single terminal input/output device.
.ne 8
.pp
The package includes the following external routines:
.(l
	Entry and Exit Functions

START				;to be marked as the starting address of the
				;program. START calls main.
exit				;exits the program, closes all files
.)l
.(l
	IO Functions

fputc				;adds a character to the specified file
fgetc				;gets a character from the specified file
fread				;reads an array from the specified file
fwrite				;writes an array to the specified file
getl				;returns a 4 byte integer from a file
getw				;returns a 2 byte integer from a file
gets				;reads a string from standard input up to
				;a newline
fgets				;reads a string from the specified file
fopen				;opens a file
fclose				;closes a file
fflush				;flushes any buffered data to the file
_flsbuf				;used by putc
_filbuf				;used by getc
putl				;puts a 4 byte integer into a file
putw				;puts a 2 byte integer into a file
puts				;puts a string onto standard output appending
				;a newline
fputs				;puts a string onto the specified file
ungetc				;look-ahead mechanism, pushes a character back
				;onto the input stream

	Storage Allocation Functions

malloc				;allocates a specified amount of storage
free				;returns malloc/calloced storage to the heap
realloc				;Makes a piece of storage larger
calloc				;allocates a specified amount of zero storage
cfree				;returns malloc/calloced storage to the heap

	String Manipulation Functions

clearn				;clears n bytes of storage
filln				;fills n bytes of storage with the specified
				;character
index				;returns the position of a string in another
rindex				;returns the position of a string in another
				;starting at the end
strcat				;appends one string to another
strchr				;returns the position of a character in a
				;string
strrchr				;returns the position of a character in a
				;string from the end
strcpy				;copies one string to another
strcmp				;compares two strings
strlen				;finds the length of a string
strncat				;same as strcat, but destination length given
strncpy				;same as strcpy, but destination length given
strncmp				;same as strcmp, but length given
strsave				;Allocates space and copies a string into it.
swap				;swaps bytes in a word (ie conversion to/from
				;pdp-11)
bufcpy				;copies exactly n bytes

	Standard I/O Functions

eprintf				;Writes onto standard error
printf				;Writes onto standard output
fprintf				;Writes onto the specified file
sprintf				;Writes onto the specified string
fscanf				;Reads from the specified file
scanf				;Reads from standard input
sscanf				;Reads from the specified string
strtol				;converts a string to a number
atol				;converts a string to a number (long)
atoi				;converts a string to a number (int)
atof				;converts a string to a number (double)

	Mathematical Functions

rand				;returns a positive pseudo-random number
				;between 0 and 2029052025-1
srand				;sets the seed of the random-number generator
jn(n,x)				;nth bessel function at x
j0(x)				;0th bessel function at x
j1(x)				;1st bessel function at x
erf(x)				;error function at x
erfc(x)				;complimentary error function at x
exp(x)				;e^x
log(x)				;natural log of x
log10(x)				;log base 10 of x
sqrt(x)				;square root of x
pow(x,y)			;x^y
sinh(x)				;hyperbolic sine of x
cosh(x)				;hyperbolic cosine of x
tanh(x)				;hyperbolic tangent of x
sin(x)				;sine of x
cos(x)				;cosine of x
tan(x)				;tangent of x
asin(x)				;arc sine of x
acos(x)				;arc cosine of x
atan(x)				;arc tangent of x
atan2(y,x)			;arc tangent of y/x with overflow protection
				;and checks that the result is in -PI to PI
.)l
.s3 "The UNIX-Subset Interface"
.pp
It is assumed that the routine START will be called (by the OS or
something) with the stack pointer initialized.
START initializes the IO system (i.e. it opens stdin, stdout, and stderr)
and calls the user's main() function with three arguments.
The first argument is 1, the second argument is a pointer to an array of
strings containing a string of length zero and a NULL, the third argument
is a pointer to another array of strings containing NULL.
That is, main is passed valid (but useless) UNIX argc, argv, and environ
parameters.
If the user's main() function returns, then START calls exit(0).
.pp
The library assumes the existence of the UNIX style functions listed
below.  These routines should use the variable errno to explain what went wrong
when problems occur (the various error codes are specified in errno.h).
.ip char\ *sbrk(size)\ int\ size ;
Sbrk should return a pointer to at least size bytes
of data.  These chunks need not be contiguous, but they
should be for compatibility with UNIX.  Sbrk returns either -1
or 0 on an error.
.ip int\ open(filename,mode)\ char\ *filename;\ int\ mode;
Open opens the file named by filename, with the indicated mode,
the modes are:
.(b
    0	=> open for reading
    1	=> open for writing
    2	=> open for reading & writing
           (this mode is not used at this time)
    1|_IO_EOF	=> open for writing and seek to eof
.)b     
Open returns a number between 0 and 19 that may
be used in subsequent calls to read, write, and
close.  On failure it returns -1.
.ip int\ creat(filename,prot)\ char\ *filename;\ int prot;
Creates and opens (for writing) a file named filename with protection
as specified by prot.  For things like terminals that cannot be created
creat just opens the device.  Creat returns a number between 0-19
that may be used in subsequent calls to read, write, and close.
On failure it returns -1.
.ip int\ read(fno,buf,size)\ int\ fno,\ size;\ char\ *buf;
Read reads at most size bytes into buf from the file connected to fno,
where fno is one of the magic numbers returned by open() or creat().
Read returns the number of bytes read, or a 0 on end of file, or a -1
on an error.
.ip int\ write(fno,buf,size)\ int\ fno,\ size;\ char\ *buf;
Write writes at most size bytes from buf into the file connected to
fno, where fno is one of the magic numbers returned by open() or
creat().  It returns the number of bytes written or a -1 to
indicate an error.
.ip int\ close(fno)\ int\ fno;
Close closes the file associated with the magic number fno, where fno
is one of the magic numbers returned by open() or creat().  It returns
0 if all goes well, -1 if something went wrong.
.ip _exit(code)\ int\ code;
Exits from the program, with a status code specified by code.
It should not return.
.s3 "Simple UNIX-Subset Implementation"
.pp
Included in the library is a very simple version of these calls that
assumes the existence of only the following functions.
.ip INCHRW()
There is one input device of interest, and characters can be read
from it by calling INCHRW() which returns a value 0..255 or -1
for error.
.ip OUTCHR(ch)
There is one output device of interest, and characters can be written
to it by calling OUTCHR(ch).  Its return will be ignored.
.ip _exit(code)
There is a way of exiting the program, and this may be done by calling
_exit(code).
.ip START()
There is a way of entering the program, and this will call START() (which
in turn calls main()) and does the file I/O initialization.
