(5-12-84) page 1 Small-C 2.1 User Notes THE DISTRIBUTION DISKETTE This diskette contains version 2.1 of the Small-c compiler. It runs under CP/M 2.2, Requires 56K bytes of RAM, and makes use of the Microsoft MACRO-80 package. The following files are on the diskette: CC.COM Executable Small-c Compiler. AR.COM Executable archive maintainer. CC.SUB C to COM compile steps. CCCC.SUB C to COM compile of the compiler NEWLIB1.SUB Extract from CLIB.ARC & compile library modules. NEWLIB2.SUB Assemble library modules. NEWLIB3.SUB Build new relocatable library from .REL files. CLIB.REL Small-C relocatable library. STDIO.H Standard header file for all compiles. AR.C Archive maintainer source. CC.ARC Small-c compiler source archive. CLIB.ARC Small-c library source archive. DOCUMENTATION For a description of the Small-c language and its library functions see "The Small-C Handbook" by James E. Hendrix (Reston Publishing Co., Reston, VA, March 1984). This document describes procedures for using the compiler, compiling the compiler, and compiling the library. Also described are some new features which were developed since publication of the book. COPYING THE DISTRIBUTION FILES First, make a copy of this diskette, then put it away for safe Keeping. Next, set up a double-density system diskette in drive A containing only the following files: CP/M: SUBMIT.COM, XSUB.COM, PIP.COM SMALL-C: AR.COM, CC.COM, *.SUB, STDIO.H, CLIB.REL MACRO-80: M80.COM, L80.COM, LIB80.COM The .SUB files assume the presence of such a diskette. The NEWLIB?.SUB files require the capacity of double-density 8" diskettes (about 500k bytes). If your drives cannot provide that capacity, it will be neccessary to modify the .Sub files to do their work in a piecemeal fashion. USING THE COMPILER The compiler translates a subset of the C language into Intel assembly language mnemonics. It supports only integer and character data types. Arrays are limmited to one dimension. It does not support arrays of pointers, structures, or unions. Also missing are sizeof, casts, #if expr, #undef, #line, and the ?: operator. External functions are automatically declared, but external variables  page 2 must be declared explicitly. Functions always return integer values. Globals may be initialized using the = syntax, but locals cannot. Locals are always automatic, and the specifiers auto, static, extern, register, and typedef are not accepted at the local level. Only extern is accepted at the global level. Character variables are expanded with sign-extension when they appear in expressions; character constants are not. To avoid clashes with user chosen names, the original Small-c 2.1 library named its system-level globals with a leading underscore character. However, versions of MACRO-80 before 3.44 rejected such names as external references. So, to accommodate users of older copies of MACRO-80, the leading underscores were changed to the letter U. The following global names are now used in the library and must, therefore, be avoided in your programs: Uadvance Ualloc Uarg1 Uauxef Uauxfl Uauxrd Uauxsz Uauxwt Ubdos Ubufptr Uchrpos Uclreof Uconin Uconout Udevice Udirty Uend Ufcbptr Ufield Ugets Ugetsec Ulex Ulink Uloadfn Umain Umemptr Umode Unewfcb Unextc Ungetc Uopen Uparse Uprint Uputsec Uread Uredirect Uscan Use Usector User Useteof Useterr Ustatus Uvec Uwrite Uxaddr Uxend Uxeof Uxflush Uxnext Uxread Uxsize Uxwrite Small-c programs (including the compiler) make use of the relocatable object-module library CLIB.REL. The module CSYSLIB contains system-level functions which are automatically loaded with every program. These functions provide for UNIX - like I/O rdirection (including concatenation of standard output) and command-line argument passing. This implementation begins program execution at main() rather than the first function as some earlier versions did. Note that "main" MUST be in lower-case letters; otherwise, the compiler will not generate "Ulink" as an external reference and the program will not link properly at load time. This implementation supports the reading of disk directories. A directory is made to look like an ASCII file of filenames, one to a line. A directory is indicated by a drive specifier without a filename. For example, the specifier B: indicates the directory on drive b. X: indicates the default directory. Fopen() and freopen() accept these "directory" names just like any other name. Directory names may also be used when redirecting the standard input file. Directory files may only be read; writing produces an error. Isatty() answers YES to directory files, cseek() returns EOF . fflush() does nothing, and ungetc() works as usual. This feature takes up .3k bytes which can be eliminated by deleting "#define DIR" in CSYSLIB.C before compiling it. The function dir() has been dropped in favor of this more generalized (and UNIX-like) approach.  page 3 The steps involved in compiling a program are documented in CC.SUB Examples of invoking the compiler follow: CC compile console input giving console output CC <FILE1 -L1 -P compile FILE1 giving console output, list the source as comments in the output, and pause on errors CC <FILE1 >FILE2 -M compile FILE1.C giving FILE2 and monitor progress by listing function headers on the console CC FILE1 FILE2 >FILE3 compile FILE1.C then FILE2.C into a single program in FILE3 CC FILE1 >FILE2 -O -A compile FILE1 giving FILE2, optimize size over speed, and sound the alarm on errors CC FILE1 compile FILE1.C giving FILE1.MAC CC FILE1 FILE2 compile FILE1.C then FILE2.C giving FILE1.MAC Any number of files may be concatenated as input by listing them in the command line; in that case stdin is not used. Standard CP/M file specifications, including logical devices, are accepted. The listing switch has two forms: -L1 lists on stdout (with output) as comments -L2 lists on stderr (always the console) Pressing control-s makes the compiler pause until another key is pressed, and control-C aborts the run. Enter a CR to resume execution after a pause because of a compile error. If input is from the keyboard, control-z indicates end-of-file, control-x rubs out the pending line, and DEL or BS rubs out the previous character. If the compiler aborts with the letter M on the screen, there was insufficient memory to run it; a 56K system is required. If it aborts with the letter R on the screen, the standard input file has a redirection error (no such file) .  page 4 USING THE ARCHIVE MAINTAINER Comments in the front of the file ar.c describe the operation of the archive maintainer AR.COM. To get a list of the contents of each archive for future use in building new archives from scratch, put a copy of the distribution diskette in drive B: and enter the commands: AR -T B:CC.ARC >CCLIST AR -T B:CLIB.ARC >CLIBLIST COMPILING THE LIBRARY This procedure requires the full capacity of a DOUBLE DENSITY diskette in drive A, set up as described above. 1. place a double density diskette containing only CLIB.ARC in drive B 2. Issue the command SUBMIT NEWLIB1 to extrace from the archive and compile each of the library modules. This temporarily relocates CLIB.ARC to drive A and produces about 80 .MAC files on drive B. The extracted .C files are deleted. 3. Issue the command SUBMIT NEWLIB2 to assemble the library modules. The .REL files are placed on drive A. You will need to respond with a control-C at the end when the assembler prompts the console with an asterisk. 4. Issue the command SUBMIT NEWLIB3 to build a new library. Drive B is erased, CLIB.ARC is moved back to b, the .REL files are moved to B, and a new CLIB.REL is created on both A and B. The .REL file should be kept so that it will not be necessary to recompile every function the next time you build a new library. The order of the modules in the library, as established in NEWLIB3.SUB, is important. It must begin with LINK and CSYSLIB and end with CALL. In between, modules are arranged as alphabetical as possible allowing for forwark references between some of the modules. Modules which are used less frequently are optimized for size over speed. COMPILING THE COMPILER To compile a new copy of the compiler from CC.ARC: 1. Place a diskette containing only CC.ARC in drive B: 2. Issue the command SUBMIT CCCC to compile and assemble each of the four major parts of the compiler and then link them together, this will leave CC.COM, CC.ARC, and the .REL files on drive B.  page 5 NEW FUNCTIONS The following functions were added after publication of the "The Small-C Handbook". - auxbuf (fd, size) int fd, size; This Small-C function allocates an auxilliary buffer of size bytes for fd. It returns zero on success and ERR on failure. Fd must be open, and size must be greater than zero and less than the amount of free memory. If fd is a device, the buffer is allocated but ignored. Extra buffering is useful in reducing disk head movement or drive switching during sequential operations. Once an auxiliary buffer is allocated it sticks for the duration of program execution, even if fd is closed. Calling this function a second time for the same fd returns ERR but, otherwise, has no effect. Alternating read and write operations or performing seeks will produce unpredictable results. Ungetc() will operate normally, however. Ordinarily, it is counter productive to allocate auxiliary to both input and output files. - ctellc(fd) int fd; This Small-c function returns the offset(0-127) to the current byte in the current buffer for fd. the current byte is the next one that will be read from or written to the file. No account of ungetc() calls is taken. - pad (str, ch, n) char *str, ch, int n; This Small-C function fills the string at str with n occurrences of the character ch. - rename (old, new) char *old, *new; This Small-C function changes the name of the file specified by old to the name indicated by new. It returns NULL on success, otherwise ERR. NEW ERROR MESSAGE - no pointer arrays This message indicates an attempt to declare an array of pointers. This version of Small-C does not support them. ERRATA FOR "THE SMALL-C HANDBOOK" The functions dtoi(), otoi(), utoi(), and xtoi() (pg. 103) return ERR if the number being converted would overflow a 16-bit word.

Small-C and Small-Tools Order Form -------------------------------------------------------------- Price Quantity Item Each Total ____ Small-C 2.1 (with handbook) 39.95 ______ ____ * The Small-C Handbook 14.95 ______ ____ Small-Tools (with manual) 35.00 ______ ____ * Small-Tools Manual (photocopied) 5.00 ______ ____ ** Small-Tools Manual (on diskette) 15.00 ______ Postage and Handling 3.00 Plus $6.00 Overseas Air Mail ______ TOTAL ______ * Applies toward later purchase of the package. ** Requires signature on distribution agreement. -------------------------------------------------------------- [ ] 8" SSSD CP/M [ ] 5.25" SD North Star CP/M [ ] 5.25" DD North Star CP/M [ ] 5.25" QD North Star CP/M [ ] 5.25" (ms) Apple CP/M -------------------------------------------------------------- NAME: ________________________________ DATE: ______________ COMPANY: ____________________ DEPARTMENT: ____________________ ADDRESS: _____________________________________________________ _____________________________________________________ _____________________________________________________ Include self-addressed, stamped envelope with queries. Enclose check, money order, or purchase order for total amount and send to: J. E. Hendrix Box 8378 University, MS 38677