This is the file CLIB;CDOC.

File: CLIB;CDOC,  Node: Top,  Previous: (DIR), Up: (DIR), Next: Basics


                    Information on Programming in C

C is an implementation language, similar to BCPL except that data is
typed.  It is the primary language used in the UNIX operating system.
This implementation runs on the ITS and TOPS-20 operating systems and is
moderately compatible with the UNIX C implementation.  The UNIX
system calls are NOT implemented, but interfaces to ITS and TOPS-20
system calls are provided.

* Menu:

* Basics::		How to run C programs on ITS.

* Details::		Differences between C on ITS and UNIX.

* Getting Started::	Hints on writing C programs.

* Support Routines::	An introduction to the routines available in the
			C runtime environment.

* Portable I/O::	The Portable I/O Library.

* Storage allocation::	A dynamic storage allocator.

* String Routines::	Basic character string routines.

* Character Arrays::	A character string package that uses dynamic
			storage allocation.

* Math Functions::	Floating point routines for the usual functions.

* Dates and Times::	Packages for manipulating and printing dates and
			times in various formats.

* System Routines::	Packages of routines for accessing operating
			system features.

* Timer Package::	Runtime support for timing procedure calls.

* Debugging::		Methods and routines for debugging C programs.

* Graphics::		Packages for graphics and for working with
			images in the new image file format.

* Miscellaneous::	Various interesting routines.

* Internals::		Internal documentation.


Node: Basics,  Previous: Top,  Up: Top,  Next: Details


                       Running C Programs on ITS

The C compiler translates C into MIDAS and automatically invokes MIDAS
to assemble the intermediate MIDAS code into a relocatable program. The
command for invoking the C compiler is

	:cc <options> file1 file2 ...

where the arguments are the filenames of the C source files which are to
be compiled.  Each file will be compiled in turn, and if the compilation
is successful, the resulting relocatable file will be placed in the file
"file STK".  Arguments that begin with a hyphen are compiler options.

	-c	Compile only, do not assemble
	-g	Do not delete the MIDAS file
	-x	Syntax check only
	-s	Produce a symbol table Listing
	-b	Compile a big function (FUNCTION TOO LARGE)

For example, the command

	:cc -g foo

would compile the C program in the file "FOO C" or "FOO >" in the
current directory, place the resulting relocatable program in the file
"FOO STK", and leave the MIDAS output in file "foo MIDAS".

Relocatable programs produced by the C compiler are loaded together
with the C support routines using STINKR.  To load program files "foo",
"bar", and "bletch" and produce a executable file "foo", use the following
STINKR commands (STINKR supplies the equal sign prompts).

	:stinkr
	=x clib;clib
	=l foo
	=l bar
	=l bletch
	=o ts foo
	=^@

The ^@ (ASCII NUL) signals end of file on the terminal input file.
These commands could also be written in a file, say "FOO STINKR",
without the NULL.  Invoking STINKR with "foo" as a JCL argument would
then execute the STINKR command file and produce a executable program.

To run the program merely type

	:foo <optional job command line>

The C startup routine will automatically parse the JCL line and pass the
components to the user main program as arguments to the main program.
Refer to node "Getting Started" for a description of these argument
passing conventions.  The arguments to the program are delimited by
spaces, so an invocation such as

	:myprog foo bar bletch

will parse into the four character strings "MYPROG", "foo", "bar", and
"bletch".  Command line arguments that contain spaces may be enclosed in
double quotes.  In addition, the startup procedure will open the TTY for
input and output on the Portable I/O Library files cin (standard input),
cout (standard output), and cerr (standard error output).

Certain argument forms are interpreted by the C startup routine as
commands for special I/O initialization.  The source or destination of
the standard I/O streams can be specified in the JCL by using the
delimiters described below.

	<	Redirects the standard input (CIN) to come from the
		indicated file.

	>	Redirects the standard output (COUT) to go to the
		indicated file.

	>>	Redirects the standard output (COUT) to be appended to
		the indicated file.

	%	Redirects the standard error output (CERR) to the
		indicated file.

The default device is DSK, the default directory is the current
directory, and the default second file name is >.  So for example, 

	:myprog foo <bar >>my;junk

will pass "MYPROG" and "foo" as arguments to the main routine,
initialize cin to read from file "DSK:sname;FOO >", initialize cout to
append output on the file "DSK:MY;JUNK >", and initialize cerr to direct
output to the terminal.  By convention, error messages are output to
cerr.  Note that if, for instance, you wanted to read the standard input
from "MY JUNK", the invocation

	:myprog <my junk

would not work.  However, the incantation

	:myprog <my.junk

will open "MY JUNK" as the standard input.  The filename conventions are
designed for compatibility with several operating systems.  Refer to the
documentation on the Portable I/O Library routines COPEN and FPARSE for
details.

Visit node "Support Routines" for an introduction to the routines
available to C users.  Visit the next node for a discussion on the
compatibility between this version of C and other implementations.
The node "Getting Started" describes some useful hints for writing
C programs. 

New users should probably read the next three nodes and then return to
this node for a second look at how to run C programs.


Node: Details,  Previous: Basics,  Up: Top,  Next: Getting Started


                    Details of Language Differences

The C compiler and the support packages were written by Alan Snyder.
The language that the compiler accepts differs in a few (mostly) minor
ways from the standard version of C as described in the standard
reference by Kernighan and Ritchie (Kernighan and Ritchie, The C
Programming Language, Prentice-Hall, 1978.)

The manual for the C compiler says that the compiler does not
differentiate between upper and lower case characters.  Actually this is
not true.  The C compiler, as well as the C standard, does differentiate
between upper and lower case.  There is no limit on the length of
identifier names recognized as unique by the compiler, although the
loader imposes a maximum recognized length of six characters for
external identifiers.  The #RENAME facility is provided to allow the use
of long names internally, while providing the assembler with shorter
names that presumably will be unique in the first six characters.  The
standard implementation limits the recognized length to 8 characters for
internal identifiers and 7 characters for external identifiers and no
RENAME facility is provided.

The C compiler conforms to the old style of syntax which means that
initializers cannot contain an equals sign and operators must be to the
right of the equals sign in assignment statements (Kernighan and
Ritchie, Appendix A, Section 17.)  Also, AUTO and REGISTER variables may
not have initializers and lists of initial values may not be nested.
Structures may be initialized, but the compiler is not clever about
matching initial values with structure components.  It is safe to
initialize structures of integers and pointers, but initializing more
complicated structures may not work.

The UNION data type is not supported and its use will yield a syntax
error.  It is easy to program around this limitation by passing a
pointer to a procedure.

The TYPEDEF facility is not fully supported, but it seems to work for
most common cases.

The REGISTER storage class specifier is not supported.  The compiler
will handle the specification as if AUTO were the requested storage
class.  (The 'register' will be allocated from the stack.)

Type CASTING (forcing type conversions by placing a type declaration,
enclosed in parantheses, in front of an expression) is not supported.

Access to parts of words is not supported except by means of shifting
and masking.  If you use FIELDS the compiler will allocate one word per
field.  (The code generated by the UNIX C compiler for accessing fields
is not very good anyway.)

In the standard implementation of structures, the names of all structure
members must be unique (unless the structure members have the same
offset) and any pointer value may be used in conjuction with any
structure member.  In this implementation, the names of structure
members need not be distinct, but a structure member may only be
accessed by a pointer value that has type "pointer to structure" for the
structure to which the component belongs.

The storage types INT, LONG INT, SHORT INT, and UNSIGNED INT are all
equivalent to INT, which allocates one 36 bit 2's-complement word.

The sign bit of characters is not propogated into the high order bits
when type CHAR is converted to type INT.  Such sign propogation is
performed on the PDP-11.

Shifting is implemented by a logical shift so the high order bits are
vacated with zeros.  On the PDP-11, arithmetic shifting is used.

The filename in INCLUDE statements may only be enclosed in quotes.

The C compiler uses a different algorithm for expanding references to
MACROS than the algorithm used in the standard implementation.  The
difference will not be apparent to most users, but designers of macro
packages will benefit from the improved algorithm used in this
implementation.

The C compiler and runtime support uses the Portable I/O Library instead
of the Standard I/O Library, which is discussed in Kernighan and Ritchie
and has superceeded the Portable Library at most installations.  The
differences are not significant, but for compatibility a package exists
which simulates Standard I/O calls by calling the appropriate routines
in the Portable Library.  (*note Standard I/O: Miscellaneous.)

There are various other minor differences which probably will not effect
the average user.  For the full story, consult the C reference manual
written by Alan Snyder (Ritchie and Snyder, C Reference Manual, March 2,
1977), which is a detailed rewrite of the UNIX C Reference Manual.


Node: Getting Started, Previous: Details, Up: Top, Next: Support Routines


               Hints on Coding Style and Common Pitfalls

Although some C compilers do not differentiate between upper and lower
case, it is considered good C coding style to use the following
conventions.

	1.  Keep all C keywords in lower case.  This will insure
	    compatibility with the standard C implementation.

	2.  Use all upper case for the names of macros, compile time
	    constants, and user defined data types.

	3.  Begin the names of local variables used in macro packages
	    with an underscore to reduce the chance of conflict with
	    variables defined by the user of the package.


For EMACS, currently the best mode available for editing C programs is
Fundamental Mode.  If you set the variables QComment Start to "/* "
(without the quotes, but note the space) and QComment End to " */",
then comments may be inserted, deleted, and adjusted using M-; C-M-;
and C-;.  Set QComment Column to the desired starting column for
comments (around 36).  (*note More Information: (INFO;EMACS >)Programming.)


In some situations you must be careful about how you use spaces.  Does
x=-10 assign minus ten to x or decrement x by 10?  (I don't remember.
Try x =- 10 or x = -10.)  Does

	#define FOO (X,Y)

declare a macro of two arguments, or does it declare FOO to have the
value (X,Y)?  (The later case applies, but be careful.)

Amoung the other problems that users frequently stumble over is the
restriction on the use of ++ and -- for incrementing and decrementing
variables.  The C standard does not allow variables of type float or
double to be the targets of these operands and all C implementations
adhere to this restriction.

The placement of semicolons in programs is sometimes confusing, but the
rule is actually very simple.  A statement is either an expression that
ends in a semicolon or it is a compound statement, which is a sequence
of statements enclosed in curly brackets.  So

	if(x < y) x = y; else y = x;

is correct, but

	if(x < y) x = y else y = x;

is not, nor is

	if(x < y) {x = y; y = 0;}; else y = x;

which has an extra semicolon after the right curly bracket.


Node: Support Routines, Previous: Basics, Up: Top, Next: Portable I/O


                  A Introduction to the Shared Library


This node briefly describes a useful subset of the routines available in
the Shared Library.  For more complete documentation consult the other
nodes in this tree.  Begin with the next node to see all documentation
on the available support packages.  Note that not all packages are
included in the Shared Library.  For example, the job manipulation
routines are not included.  (*note Jobs: Job Handling.)

When a C program is loaded the STINKR command "x clib;clib" executes a
STINKR command file that creates links to the C library CLIB (which is
also called the Shared Library since at runtime it is shared by all
users running C programs.)  This library includes a very general package
for I/O (the Portable I/O Library), some basic character string routines,
the standard mathematics functions, interfaces to ITS system calls, and
the C runtime support package which reads and parses the JCL line and
initializes the standard input, output, and error output I/O streams.

Before describing some of the routines that are available the relevant
terminology must be introduced.  A variable of type SIXBIT is a word
containing left justified sixbit characters.  A FILESPEC is a structure
of four SIXBIT variables which contain the device, first filename,
second filename, and directory.  A filename is a character string
containing an ITS filename in the form "device:directory;first second".
A pathname is a character string that contains a UNIX-style
representation for filenames.  The format is
"/device/directory/first.second".  If the device specification is
omitted the file specification is written as "directory/first.second".
The pathname form "first.second" is useful for passing both first and
second filenames to a program on the command line.  In filenames and
pathnames, delimiters may be quoted with control-Q.  A file descriptor
is used by the Portable I/O Library to identify files and may be taken
to be of type int.  The file descriptor is not an ITS channel number,
although it is sometimes referred to as a channel.

In general, users should try to avoid circumventing the Portable I/O
Library by using the ITS system calls directly.  However, access to the
lower level I/O primitives provides the user with features such as
unbuffered TTY input and random access I/O that are not implemented in
the Portable Library.  The Library performs fully buffered I/O, so
random access block I/O will not work properly.  For random access I/O,
use the system interfaces open, close, sysread, syswrite, and access.
The Portable I/O Library searches for unused I/O channels so users who
open files by using the system interface routine 'open' will not clash
with the Portable Library.


                         PORTABLE I/O ROUTINES

The C startup procedure initializes the global variables cin, cout, and
cerr as file descriptors for the standard input, standard output, and
standard error output streams.

copen (filename, mode, options)
	Open the indicated file and return a file descriptor or -1 if
	the open failed.  The filename argument can be either a filename
	or pathname specification.  The mode is a single character, 'r'
	for read, 'w' for write, and 'a' for append to end of file.  Read is
	assumed if the mode argument is omitted.  The options argument
	is usually omitted.  The option "b" denotes binary (image mode)
	I/O and "s" denotes I/O to an incore buffer.  The buffer pointer
	is supplied in place of the filename.  Note that the mode has
	type character while the options variable has type pointer to
	character.

cgetc (fd)	Read a character from the indicated file descriptor and
		return it or return 0 if end of file.

cputc (c, fd)	Write a character to the indicated file descriptor.

ceof (fd)	Test for end of file.
cclose (fd)	Close file.
closall()	Close all files opened by copen.

cflush(fd)	Force out buffer contents on output stream.
rew(fd)		Reset file to beginning.

ungetc(c, fd)	Push character back into stream.

getchar ()	Equivalent to cgetc (cin).
putchar (c)	Equivalent to cputc (c,cout).

gets (s1)	Read a line from cin.
puts (s1)	Write string and newline to cout.

cprint (fd, format, arg1, arg2, ...)
	Formatted print statement like printf in the Standard I/O Library.
	The format is a string which may contain format items of the
	form %nf, where n is an optional decimal integer taken to be the
	minumum field width and f is one of the following characters.

		d - Print next argument (an integer) in decimal
		o - Print next argument (an integer) in octal
		s - Print next argument (a string)
		c - Print next argument (a character)

	The file descriptor can be omitted, in which case cout is used.

cgeti (fd)	Read an integer in image mode.
cputi (i, fd)	Write an integer in image mode.

cexit (cc)	Terminate job and close all files.  Returning from the
		main routine will have the same effect.

fparse (fn,f)	Convert file name or path name to FILESPEC.
prfile (f,fn)	Convert FILESPEC to file name.

istty (fd)	Return Boolean value indicating whether file is a TTY.
itschan (fd)	Return the actual ITS channel number corresponding to
		the file descriptor.

fprint(x,fd)	Print the floating point number x on the indicated file.
atoi(s)		Convert string to integer.  The first character must be
		a digit or minus sign and the conversion is always
		performed in base ten.


                            TTY I/O ROUTINES

utyi ()		Read character from TTY in unbuffered and unechoed mode.
		The TTY is opened if necessary and the output buffer is
		flushed before the read.
utyo (c)	Output the character to the TTY in unbuffered mode.
		The TTY is opened if necessary and the output buffer is
		flushed before the write.
tyo_flush()	Flush the TTY output buffer.
setprompt(s)	Set the default TTY input prompt character string.
spctty(c)	Outputs a ^P code to the TTY.

It is alright to use these TTY routines while also using the Portable
I/O Library for terminal I/O.


                           STORAGE ALLOCATION

calloc (n)	Return pointer to block of n characters.
cfree (p)	Free storage pointed to by p.  The storage must have
		been allocated calloc.

salloc (n)	Allocate a block of n words and return a pointer to it.
sfree (p)	Free storage allocated by salloc.


                         BASIC STRING ROUTINES

slen (s)	Return string length.
stcpy (s1, s2)	Copy string from S1 to S2.
stcmp (s1, s2)	Return TRUE if character strings are equal.
upper(c)	Return upper case version of character.
lower(c)	Return lower case version of character.

The Portable I/O Library contains routines for manipulating SIXBIT
characters and strings.  (*note SIXBIT: Portable I/O Library.)
The character string package contains routines for manipulating byte
pointers and bit arrays.  (*note Bytes and Bits: String Routines.)


                       INTERFACES TO SYSTEM CALLS

This is a partial summary of the system calls currently available to
users of the Shared Library.  Refer to (*note Details: System Routines.)
for more complete documentation.

open (fs, mode)
	Open channel specified by FILESPEC and return ITS channel number
	or negative ITS failure code.  The mode refers to the ITS file
	access mode bits, not the character codes used by the Portable
	I/O Library.  The routine searches for an unused channel.


sysread (ch, buffer, size)	Block input IOT.
syswrite (ch, buffer, size)	Block output IOT.

access (ch, i)			Set file access pointer.
fillen (ch)			Return file length.

close (ch)			Close the channel.

fdate = rfdate (ch)		Read file creation date.
fdate = sfdate (ch, fdate)	Set file creation date.
fdate = srdate (ch, fdate)	Set file reference date.
rauth (ch)			Read file author in SIXBIT.
sauth (ch, w)			Set file author in SIXBIT.

rsname ()			Return sname in SIXBIT.
runame ()			Return uname in SIXBIT.
ssname (w)			Set sname to value supplied in SIXBIT.

sleep (n)			Sleep for n 30th seconds.

valret (s)			.VALUE a character string or zero.

etime()				Return system elapsed time in 1/60 sec units.
cputm()				Return job CPU time in 1/60 sec units.
getcpu()			Return job CPU time in 4.096 micro sec units.


The Portable I/O Library contains routines for handling SIXBIT data
(*note SIXBIT: Portable I/O Library.) and there is a package of routines
for manipulating and printing dates and times.  (*note: Dates and Times.)

Some useful definitions are available in the file CLIB;CLIB H.


Node: Portable I/O, Previous: Basics, Up: Top, Next: Storage Allocation


                        The Portable I/O Library

Most of the routines in the Portable I/O Library are written in C, but
the most frequently used I/O routines have been hand coded in MIDAS.
The C source routines will be described first, followed by descriptions
of the MIDAS source routines and internal data structures.

The routine for opening files is COPEN.  The arguments to COPEN are a
character string which is a file name or path specification, an optional
character which indicates the mode of access, and an optional character
string containing option codes.  The modes are

	'r'	Open file for read access.
	'w	Open for write access.
	'a'	Open the file for write access and position the file
		access pointer at the end of the file.

The default mode is 'r' for read.  Normally, I/O is character oriented
and produces text files.  In particular, the lines of a text
file are assumed by the user to be separated by newline
characters with any conversion to the system format performed
by the I/O routines.

If an options string is given and contains the character "b",
then I/O is integer oriented and the file is processed in image mode.

If an options string is given containing the character "s" then I/O is
performed to or from a buffer in memory.  A pointer to the buffer is
passed in place of the filename argument.  Closing a string I/O file
that is open for write will append a NULL character to the string and
return a character pointer to that character.

COPEN returns a CHANNEL, which is a pointer to a control block, if the
open is successful.  It and returns -1 in case of error and leaves the
system error code in the external variable CERRNO.  The macro variable
OPENLOSS is frequently set to -1 in macro packages.

The default filename components are DSK for the device, SNAME for the
directory, and > for the second filename.  No default is supplied for
the first filename.  COPEN is careful to treat the TTY as a special
case.  If a disk file is locked, then COPEN will wait until the file can
be opened.

The routine GETCHAR takes no arguments, reads a character from the
standard input, and returns it.  Zero is returned on end of file.

The routine GETS takes a character pointer as an argument and reads one
line from the standard input, placing the null terminated line into the
buffer.  The newline character is not included.  No value is returned
and the buffer is assumed to be large enough.

The routine PUTCHAR takes a single character as an argument and writes
it on the standard output.  The character is returned.

The routine PUTS takes a character pointer as an argument and writes the
character string and a NEWLINE on the standard output.  No value is
returned.

The routine FPRINT takes a single or double precision floating point
number and a file descriptor as arguments, and prints the floating point
number on the specified file.  Both arguments are required.  Eight
significant digits are printed in either fixed or floating point
notation depending on the magnitude of the number.

The routine ATOI takes a character string as an argument and returns an
integer.  The first character must be either a digit or a minus sign and
radix 10 is always used.

The routine MOPEN is called by COPEN to open a file.  The TTY is treated
as a special case and MOPEN will wait on a locked file until the file
becomes available.  MOPEN requires a FILESPEC and a code word of ITS
access mode bits as arguments.  MOPEN calls OPEN to open non-TTY files.
If the file is successfully opened, the ITS channel number is returned,
otherwise the negative ITS failure code is returned.

The routine MCLOSE can be used to close a channel opened by MOPEN.  An
attempt to close the TTY is ignored.  A file opened by a call to COPEN
must be closed by a call to CCLOSE, not MOPEN.

The routine FPARSE will convert an ASCIZ string representation of an ITS
filename or pathname to a FILESPEC.  The routine requires a character
string pointer to the filename and a pointer to a FILESPEC block.  Zero
is returned if the filename could be parse and -1 is returned if the
format was incorrect.

The routine PRFILE will convert a FILESPEC into a filename in ITS
format.  The arguments are a pointer to the FILESPEC and a character
string pointer to a buffer that is assumed to be large enough for the
resulting filename.  Control-Q is placed in front of delimiters that
occur in the components of the filename.

The routine FOPEN calls FPARSE to parse a filename and then calls OPEN
to open the file.  The default filename components are DSK for device
and RSNAME for directory.  There are no defaults for the first or second
filenames which s why this routine is almost never used.  But if you
really wich to use it, the arguments are a character string pointer to
the filename and an integer containing the ITS mode bits.  The ITS
channel number is returned if the open is succesful, otherwise the
negative ITS failure code is returned.

The routine OPEN takes a FILESPEC and a integer containing the ITS mode
bits, opens the indicated file, and returns the ITS channel number if
the open was successful and the negative ITS failure code if the open
was unsuccessful.  The routine calls CHNLOC to find an available channel.
(*note: System Calls.)

The routines FXARG, C0OPEN, C0INIT, and PRSARG are called by the C
startup procedure to open the TTY as the standard input, output, and
error output I/O streams, parse the JCL, and redirect the standard I/O
streams if the JCL line contains specifications for standard I/O
redirection.

The routine VALRET takes an ASCIZ character string as an argument and
valrets the command string.  In some cases the command string will be
overwritten with garbage.

The following two routines take a single character as an argument and
return a character of the indicated type as a result.

	CCTO6	Convert ASCII character to sixbit
	C6TOC	Convert sixbit character to ASCII

The routine CSTO6 takes a character string pointer as an argument and
returns an integer containing the left justified sixbit representation
of the ASCII character string.  The routine C6TOS takes an integer and a
character string pointer as arguments and expands the sixbit characters
in the integer into the character buffer.

The following Portable I/O routines were hand coded in MIDAS.  The
calling sequences of most of these routines are described in the node on
Support Routines (*note MIDAS I/O Routines: Support Routines.)
All of the routines take Portable I/O file descriptor pointers as
arguments, not ITS channel numbers.

	CGETC		Read character
	CPUTC		Write character
	CGETI		Read integer in image mode
	CPUTI		Write integer in image mode
        UNGETC          Push character back into I/O stream
	CEOF		Test for end of file
	CFLUSH		Flush buffer
	REW		Reset channel to beginning
	CCLOSE		Close file
	CLOSALL		Close all files
	ISTTY		Return true if file is a TTY
	CISFD		Return true if pointer is a file descriptor
	ITSCHAN		Return the ITS channel number corresponding
			to the file desciptor


In the Portable I/O Library, the file descriptor points to a file
control block that contains the information on the state of the file.
The structure of a Portable I/O Library file control block is described
below.  The fields begin at the left edge of the word.

	struct FCB {
           int *fbuffp  : 18,       /* Pointer to buffer */
                fchan   :  4,       /* ITS channel number */
                fdevice :  6,       /* Device code */
                fflag   :  8;       /* Flag bits (described below) */
           int *fbprt,              /* Pointer to next
				       character or word in buffer */
                fbnt,               /* Number of characters
				       or words in buffer */
           int  fucnt   : 18,       /* Number of characters
				       in UNGETC buffer */
               *fuptr   : 18;       /* Pointer to UNGETC buffer */
           int  fclsr() : 18;       /* Address of close routine */
           int  fngetr(): 18;       /* Address of normal close routine */
           int  fgetcr();           /* Address of CGETC routine */
           int  fputcr();           /* Address of CPUTC rouine */
        };

        typedef FCB *FD;            /* Type definition for the file descriptor
                                       returned to the user */

/*  Flag bits for the fflag field in the FCB  */

#define PHYEOF   01       /* Physical EOF */
#define OPEN     02       /* File is open */
#define WRITE    04       /* Write access */
#define TTY     010       /* File is TTY */
#define UNSET   020       /* Device and channel not yet set */


The size of the buffers used by the Portable I/O Library are 200 octal
words.  A maximum of ten Portable I/O Library files may be open at any
time.  The number of character that may be pushed back into the I/O
stream is limited to 20.

The source for the Portable I/O Library exists in the several files in CLIB;

	C10IO  C	Most of the routines that are written in C
	FPRINT C	The floating point print routine
	ATOI   C	The ASCII string to integer converter
	C10MIO CMID	The core routines written in MIDAS


Node: Storage Allocation, Previous: Basics, Up: Top, Next: String Routines


                           Storage Allocation

The Shared Library provides a storage allocator for use by C users.  The
storage allocator maintains a linked list of free blocks and merges
adjacent free blocks to minimize fragmentation.  The operating system is
called to obtain additional memory pages only when necessary.  The
allocator will return a pointer to a zeroed block of the requested size.

calloc (size)		Returns a pointer to a zeroed block of
			characters of the requested size.

cfree (p)		Frees a block allocated by calloc.  The blocks
			may be freed in any order, but it is a gross
			error to free a block that has not been
			allocated by calloc.

salloc (size)		Allocate a zeroed block of words of the
			requested size.

sfree (p)		Free a block allocated by salloc.

alocstat (nwalloc, nbfree)
	Compute allocation statistics.  The number of free words is
	returned.  The number of words that have been allocated by the
	operating system and the number of free blocks are returned via
	pointers supplied as arguments.

getcore (size)		Calls the page allocation routine in the page
			handling package to obtain the requested amount
			of space and updates the allocation statistics.
			This routine is for internal use.


The source code is in the files CLIB;ALLOC CMID and CLIB;C10COR CMID.


Node: String Routines, Previous: Basics, Up: Top, Next: Character Arrays


            Character String Routines and Related Functions

The Shared library includes several basic routines for manipulating
character strings, byte strings, and bit strings.

slen (s)	Returns the length of a character string excluding the
		terminating null character.

stcpy (s1, s2)	Copies string s1 to s2 and returns a pointer to the null
		byte at the end of the new copy.  The space occupied by
		s2 is assumed to be large enough for s1.

stcmp (s1, s2)	Returns TRUE is character strings s1 and s2 are the same
		length and have equal contents.

lower (c)	Convert character to lower case.

upper (c)	convert character to upper case.

bget (s, i)	Extract the i th bit from the bit string stored at s.
		The bit string begins on a word boundary and the index
		origin starts at zero.

bset (s, i)	Set the i th bit.

ildb (pbp)	Do an increment and load byte on the byte pointer stored
		at the address supplied as an argument.

idpb (ch, pbp)	Do an increment and deposit byte with the byte and byte
		pointer address supplied as arguments.

These routines are in the file CLIB;STRING CMID and all of these routines
are in the Shared Library.


A couple of basic string pattern matching routines are contained in the
file CLIB;MATCH C.  The routines defined in this file are described below.

	smatch (p, s)	The pattern p is a character string which is to
			be matched against the data string s.  Certain
			characters in p have special meanings.

		'*'	Match any substring
		'?'	Match any character
		'\\'	Quote following character


	sindex (p, s)	Return the index of the first occurrence of the
			string p in the string s.  Return -1 if p does
			not occur in s.


Both of these routines are included in the Shared Library.


An interface to the PDP-10 block transfer (BLT) instruction has been
provided as a routine in the source file CLIB;BLT CMID.

	blt(source, dest, number)	Will transfer the indicated
					number of words from the source
					address to the destination
					address.

This routine is available in the Shared Library.


The Portable I/O Library contains routines for converting between
characters and strings in sixbit and ASCII formats.
(*note SIXBIT: Portable I/O Library.)


Node: Character Arrays, Previous: Basics, Up: Top, Next: Math Functions


                      Array of Characters Package

The array of characters package supports operations on character strings
stored in a representation that allow the strings to grow and shrink
dynamically.  The routines in the array of characters package use the
dynamic storage allocator that is included in the Shared Library.
(*note Dynamic Storage: Storage Allocation.)

The data structures used in the package can be defined by

struct rep {                        /* The representation for an
                                       array of characters */
       int count;                   /* Reference count */
       char *s;                     /* Character buffer pointer */
       int csize;                   /* Logical size of the array */
       int msize;                   /* Actual size (at least csize + 1) */
};

typedef rep *AC;                    /* What the user works with */


The functions supported by the package are described below.

	ac_new () => ac			create empty array
	ac_alloc (size) => ac		create empty array withpreferred size
	ac_create (string) => ac	create with initial value
	ac_xh (ac, c) => c		extend array with character
	ac_trim (ac) => ac		trim excess storage
	ac_fetch (ac, i) => c		fetch character from array
	ac_link (ac) => ac		make new link to array
	ac_unlink (ac)			remove link to array
	ac_puts (ac, f)			print array
	ac_cat (ac, ac) => ac		concatenate arrays
	ac_copy (ac) => ac		copy array
	ac_string (ac) => *char		return string version
	ac_size (ac) => size		return current size of array
	ac_flush (ac)			make array empty
	ac_n () => int			return # of active arrays


The default initial storage allocation for creating character arrays is
8 words.  One character is stored per word.

The source for the array of characters package is in CLIB;AC C.


Node: Math Functions, Previous: Basics, Up: Top, Next: Dates and Times


                        Floating Point Routines

All routines accept a single argument that is of type float or double.
Note that C converts all floating point arguments to double precision.

Most of the floating point routines are in CLIB;CFLOAT CMID.  The functions
contained in this package are listed below.

	LOG	EXP	COS		SIN
	ATAN	SQRT	DTRUNCATE	DROUND	DABS


In addition, a random number generator was borrowed from MUDDLE and
exists in the file CLIB;RANDOM CMID.  Two routines are available.

	SRAND		Set the random number generator seed
	RAND		Get a random number.
			The number is a large integer.


Both of these packages are in the Shared Library.



Node: Dates and Times, Previous: Basics, Up: Top, Next: System Routines


                         Date and Time Routines

This node documents the routines that are available for manipulating
dates and times in various formats.  To acquire a file date or the
running time of a program consult the documentation on system calls.
(*note Calls: System Calls.)


The date manipulating routines handle three representations for dates.

(1)	CAL	Calender date, a system-independent representation
		consisting of a record containing six integers
		for the year, month, day, hour, minute, and second.

(2)	FDATE	The ITS date representation used in file directories.

(3)	UDATE	The UNIX date representation, seconds since
		Jan 1, 1970, GMT.

The routines for manipulating these date representations are

	u2cal (udate, cal)	Convert UDATE to CAL format
	udate = cal2u (cal)	Convert CAL format to UDATE format
	f2cal (fdate, cal)	Convert FDATE to CAL format
	fdate = cal2f (cal)	Convert CAL format to FDATE
	prcal (cal, fd)		Print the date and time in CAL format
				  using the Portable I/O Library file
				  descriptor supplied in the call 

The structure of a CAL format date can be described by the following
structure.

	struct CAL {int year, month, day, hour, minute, second;};

Note that the routines that manipulate CAL format dates require a
pointer to such a structure.  All of these date handling routines are
available in the Shared Library.  The source is in the file CLIB;DATE C.


For printing times, the following routine is useful

	pr60th (time, fd)	Will print the time (supplied in units
				of 1/60 seconds) using the Portable I/O
				Library file descriptor supplied in the
				call.  The display format is HH:MM:SS.XX

The source for this routine is in CLIB;PR60TH C.  This routine is included
in the Shared Library.


Node: System Routines, Previous: Basics, Up: Top, Next: Timer Package


                            System Routines

This node documents packages of routines that manipulate system
resources such as jobs and memory pages, implement a facility for
handling exceptional program conditions, and provide interfaces to
operating system calls.

* Menu:

* TTY I/O Routines::	A package for terminal I/O.

* Interrupts::		A package for handling user program interrupts.

* Job Handling::	A package for manipulating ITS jobs.

* Page Handling::	A package for hacking memory pages.

* System Calls::	A package of interfaces to ITS system calls.


Node: TTY I/O Routines,  Up: System Routines,  Next: Interrupts


                          The TTY I/O Package

This node documents the facilities provided by the TTY I/O Package for
performing terminal I/O.  Note that this package is used by the Portable
I/O Library for performing TTY I/O and since the Portable I/O Library
provides a more general I/O interface, users are advised to avoid
circumventing the Portable I/O Library by calling the TTY I/O routines
directly.  However, the TTY I/O Package provides certain facilities that
are not available in the Portable Library such as unbuffered terminal
input.  The TTY I/O routines may be used in conjunction with the
Portable I/O Library for performing terminal I/O without conflict.


tyiopn()	Open the TTY input channel.  The channel number of the TTY
		input channel is returned.  Even if this routine is
		called several times the TTY input channel is only
		opened once and only one input buffer is maintained.

tyi()		Read a character from the TTY.  The transfer is fully
		buffered.

utyi()		Read a character from the TTY.  The transfer is
		unbuffered and unechoed.  The TTY output buffer will be
		forced out before the read is performed.

get_buf(buffer, size, break, prompt)
		Read a string from the TTY into the indicated buffer
		until the buffer is filled, a NUL character is received,
		or the indicated break character is received.  The
		indicated prompt string (or the default prompt string,
		as set by setprompt) is output to the terminal,
		unless characters are already available in the TTY input
		buffer.  The number of characters read is returned.

setprompt(s)	Set the default prompt for terminal reads via tyi().

tyoopn()	Open the TTY output channel.  The channel number is
		returned.  Even if this routine is called multiple
		times, only one TTY output channel is created and only
		one TTY output buffer is maintained.

tyo(c)		Output the character to the TTY.  The transfer is fully
		buffered.

utyo(c)		Output the character to the TTY without buffering.  The
		TTY output buffer is forced out before the transfer.

spctty(c)	Output the display code without buffering.  The TTY
		output buffer is forced out before the code is output.

tyos(s)		Output the character string to the TTY with buffering.

tyo_flush()	Force out the TTY output buffer.  The characters are
		written out using an SIOT operating system call.

The global variable ttynp contains the address of the ^L handler.  The
default ^L handler is ttxnp.  When a ^L is encountered in the input
stream, the prompt and the input buffer are redisplayed and the output
buffer is forced out.  Before the prompt is redisplayed a carriage
return or the special display code 'C' is output, depending on whether
the terminal is a display.


There are two routines that are internal to the TTY package.

ttyih()		TTY interrupt handler
ctrlch(c)	Return display width of character


The source code for the TTY I/O Package is in CLIB;C10TTY C.


Node: Interrupts,  Up: System Routines,  Next: Job Handling


                        The C Interrupt Package

The file CLIB;C10INT CMID contains the code for the C interrupt handling
system.  Two basic routines are provided by this package for setting an
interrupt handler and signalling an interrupt.

on (number, handler)	Specifies the routine to be invoked when the
			interrupt occurs.  A pointer to the new handler
			is provided in the call.  The address of the old
			interrupt handler is returned.  The number
			supplied in the call is one of the code numbers
			used in the C interrupt system. 

signal (number)		Signal the specified interrupt.


Default handlers have been provided for ^S and ^G interrupts.  The
default ^S handler flushes the TTY output buffer and inhibits output.
The default ^G handler flushes the TTY output buffer, inhibits output,
and produces a dump of the runtime stack.

The code numbers used by the C interrupt system are defined in CLIB;C DEFS.
All of the routines described above are in the Shared Library.


Node: Job Handling,  Up: System Routines,  Next: Page Handling


                     Routines for Manipulating Jobs


Two simple routines for executing inferior jobs are available, but these
routines are not included in the Shared Library.


execs (pname, args)		Execute a program with the supplied command string.

execv (pname, argc, argv)	Execute a program with the supplied
				argument vector which is in the same
				format as the parameters of a main routine. 

Both routines return the following return codes.

	-5		Job valretted something and was not continued
	-4		Internal fatal error
	-3		Unable to load program file.d
	-2		Unable to create job
	-1		Unable to open program file
	0		Job terminated normally
	other		Job terminated abnormally with said PIRQ

Both routines set the following global variables.

	exctime		Job CPU time in 1/60 sec. units
	exccode		Contents of job's loc 1 at termination

The source for these routines is in CLIB;C10EXC C.


For more sophisticated job handling, use the package in CLIB;C10JOB C.
These routines are not included in the Shared Library.

The representation of a job is an integer with a value from 0 to 7,
indicating the inferior job number.

	j_create (jname) => # or error code

	j_load (filespec) => # or error code
	j_fload (file_name) => # or error code
	j_cload (channel, jname) => # or error code
	j_own (uname, jname) => # or error code

		error codes:

		-1	unable to open program file
		-2	unable to create job
		-3	unable to load job
		-4	fatal error
		-5	(OWN) no such job
		-6	(OWN) job not yours

	j_start (#) => rc	(return code: non-zero => error)
	j_stop (#) => rc
	j_disown (#) => rc
	j_forget (#) => rc
	j_kill (#) => rc
	j_snarf (#, inferior_name) => rc
				(disown named inferior from stopped job)
	j_give_tty (#) => rc
	j_take_tty (#) => rc

	j_grab_tty ()		(grab tty if given to some inferior
				 and stop job)
	j_retn_tty ()		(return tty to inferior and restart)

	j_wait (#) => status	(waits for non-zero status)
	j_sts (#) => status

	j_onchange (f)		(set handler for status changes)

	j_sjcl (#, s) => rc	(set jcl for job)
	j_jcl (#) => s		(get jcl)
	j_ch (#) => ch		(return block image output channel to job)
	j_name (#, filespec)	(set filespec to job name)

	j_val (#) => s		(return string valretted by job)
	j_fval (#)		(flush valret string; or call cfree)

	Job Status:

		-5 => stopped, ^Z typed
		-4 => stopped (by superior)
		-3 => stopped, valret
		-2 => stopped, requested suicide
		-1 => no job
		 0 => running
		>0 => stopped, value is job's first interrupt word


Node: Page Handling,  Up: System Routines,  Next: System Calls


                 Routines for Manipulating Memory Pages


The routines documented in this node provide capabilities for managing
memory pages.  In order to avoid conflicts with other routines in the C
runtime environment, these routines should be used for allocating memory
pages.  Note that the storage management routines documented elsewhere
in this file use these page handling routines, so the manipulation of
memory pages via these routines in conjunction with the use of the
storage allocation package is permissible.


pg_get (n)
	Allocates n contiguous, unused pages in the address space.
	The number of the lowest page allocated is returned.  If the
	request cannot be met, -1 is returned.

pg_ret (page, n)
	Deallocates n pages in the address space, starting
	with the page number supplied in the call.  The
	routine returns a nonzero value if an error occurs.

pg_exist (page)
	Returns TRUE if the page exists in the address space.

pg_nshare (page)
	Return number of times that a page is shared.

The source for these routines is in CLIB;C10PAG C and all of these routines
are available in the Shared Library.


There are two routines available in the Shared Library for mapping disk
files into memory.


filmap (chan, offset, size)
	Map part of the disk file open on the specified channel into
	memory.  The size and offset, in words, of the section to be
	moved into memory is specified in the call.  The routine returns
	a pointer to the beginning of the section in memory.  If the
	mapping fails because of insufficient memory space, the routine
	prints an error message on the standard output and returns
	zero.  If an error occurs while reading a page, then an error
	message is printed on the standard output and a ponter to the
	section successfully read is returned.

filunmap (ptr, size)
	Frees pages mapped into memory by filmap.  The size of the
	section in words and a pointer to the section are supplied in
	the call.  The contents of the pages are not copied back to
	the file.


The source for these two routines is in CLIB;C10MAP C and the routines are
included in the Shared Library.



Node: System Calls,  Up: System Routines,  Next: System Routines


            ITS System Calls Supported by the Shared Library

This node documents the system calls that are available through
interfaces in the Shared Library.  Before using the routines listed
here, you should check the nodes pertinent to your application to
determine whether there are other routines available that provide more
amicable interfaces to the operating system.

In general, the system call interfaces are written so that argument
values for the calls are provided as arguments of the procedure
invocation, in the order in which the arguments are expected in the
call, and the routines return the negative value of the ITS failure code
if an error occurs.  Note that all channel numbers are ITS channel
numbers, not Portable I/O Library file descriptors, all names are in
sixbit, and all dates are in ITS date format.  A package has been
written for manipulating dates and is described in this file.
(*note Dates: Dates and Times.)


sysopen (chan,  filspc,  mode)		Open the specified channel
close (chan)				Close the specified channel
chnloc()				Find and return the number of an
					  unused channel
uiiot (chan)				Perform a unit input IOT
uoiot (chan, data)			Perform a unit output IOT
sysread (chan, buffp, nwords)		Perform a block input IOT
syswrite (chan, buffp, nwords)		Perform a block output IOT
siot (chan, bytp, nbytes)		String IOT

sysfinish (chan)			Force output to finish on the
					  specified channel and wait for
					  completion
sysforce (chan)				Force output to finish, but do
					  not wait

reset (chan)				Reset channel
status (chan)				Get channel status
rfpntr (chan)				Read file access pointer
access (chan, pos)			Perform random access on channel
fillen (chan)				Return the file length in units
					appropriate to the mode in which
					  the file was opened
filnam (chan, filspec)			Get file name by which channel
					  was opened
rauth (chan)				Read the name of the author of
					  the file
sauth (chan, author)			Set the name of the file author
rdmpbt (chan)				Read the file dump bit
sdmpbt (chan, bit)			Set the file dump get
sreapb (chan, bit)			Set the file reap bit
rfdate (chan)				Read the file creation date
sfdate (chan, fdate)			Set the file creation date
srdate (chan, fdate)			Set file reference date
dskupd (chan)				Update file information
resrdt (chan)				Restore file information

ttyget (chan, block)			Get TTY status
					  (writes 3 values into the block)
ttyset (chan, block)			Set TTY status
					  (reads 3 values from the block)
cnsget (chan, block)			Get console status
					  (writes 5 values into the block)
cnsset (chan, block)			Set console status
					  (reads 5 values from the block)

whyint (chan, block)			Return block of information on
					  interrupt status
ityic (chan)				Read tty interrupt character
syslisten (chan)			Listen for input on the channel
					  (the number of characters is returned)
rcpos (chan)				Read TTY cursor position as half
					  words (v,,h)
scml (chan, number)			Set the number of command lines
					  at the bottom of the screen

getcpu ()				Return cpu time in 4.069 micro seconds
cputm ()				Return cpu time in 1/60 seconds
sleep (time)				Sleep for time specified in
					  1/30 second units
etime ()				Return elapsed time 1/60 seconds
now (pcal)				Get current date and time

corblk (a1, a2, a3, a4, a5)		Perform page hacking
cortyp (pagno, output)			Get information about page
pageid (vpn, idn)			Get named public page
pgwrit (job, vpn)			Write page to disk

rsname					Read sname
ssname (name)				Set sname
runame					Read user name

rsuset (where)				USET hacking
wsuset (where, what)
ruset (who, where)
wuset (who, where, what)
wusrvar (job, spec, value)

delete (fname)				Delete a file given an ASCIZ
					  string containing the
					  filename.  (The Portable I/O
					  routine fparse is used to
					  parse the filename.)
sysdelete (filspc)			Delete file
renmwo (chan, filspc)			Rename file open for output
sysrnm (fspec1, fspec2)			Rename file given by fspec1
syslnk (filsp1, filsp2)			Create link from fspec1 to fspec2
dirsiz (chan, block)			Get info on directory size
					  (writes 2 values into the block)

tranad (job, from, to, flags)		File translation hacking
trancl (job, flags)
trandl (job, filspc, flags)

sysload (job, chan)			Load a program
pdump (jobch, dskch)			PDUMP a program
uclose (jchan)				Destroy an inferior job
sysdisown (jchan)			Disown job
reown (jchan)				Reown job
sysdtach (jchan)			Detach job
sysatach (jchan, tty)			Attach job (TTY < 0 implies default)
atty (job)				Give tty to inferior
dtty (job)				Take tty from inferior
wfnz (ptr)				Wait for word to become non-zero
wfz (ptr)				Wait for word to become zero
val7ret (str)				Valret an asciz string
demsig (demon)				Signal a demon process

sstatus (valblk)			Get system status
					  (returns 7 values)

maktag (tagp)				Make a tag table entry
gotag (tagp)

For information on the details of the system calls consult the system
documentation.  Try

	:DOC CALL

at DDT command level.


Node: Timer Package, Previous: Basics, Up: Top, Next: Debugging


                         Timing Procedure Calls

A package of routines is available to gather statistics on the time
spent in the various procedures of a program.  The procedure calls are
monitored and a report which includes the percentage of CPU time spent
in each procedure is generated.

[This package is still being debugged and documented.]


Node: Debugging, Previous: Basics, Up: Top, Next: Graphics


                           Debugging Packages

The code produced by the C compiler contains the hooks for implementing
the C versions of Lisp BAKTRACE and BREAK.  A first attempt at BAKTRACE
exists in the file CLIB;STKDMP C.  This routine is called by the ^G handler
and so a basic back trace can be obtained by typing control-G.  The
stack dump routine displays the names of the called procedures and the
procedure arguments in octal.

These facilities will be expanded in time.


DDT provides several useful facilities for debugging C programs at the
assembly language level.

	^N	Single steps through a program.
	p,^N	When invoked at the beginning of a subroutine
		will continue execution until the subroutine returns.

There are facilities for setting breakpoints and listing memory
locations.  (*note DDT: (INFO;DDT >)Top.)



Node: Graphics, Previous: Basics, Up: Top, Next: Miscellaneous


                 Computer Graphics and Image Processing

This node documents the packages available in C for displaying graphics
and performing image processing tasks.

* Menu:

* TV Graphics::		A basic package for graphics on the Knight TV's.

* Image files::		A package for reading and writing images in the
			new image file format.


Node: TV Graphics, Previous: Graphics, Up: Graphics, Next: Image Files


                  TV Graphics Package for Knight TV's


The TV graphics package provides the basic primitives for drawing
points, lines, and circles on the Knight TV displays.  All of the
drawing functions test to see if the TV has been opened.  If it has not
been opened, the TV is opened by calling tvsetup(), which allocates
space for the TV buffer, initializes the TV buffer memory map, clears
the screen, and sets the buffer update mode to inclusive-OR mode so that
overlapping lines will not erase the common point of intersection.  The
routine tvwrite uses a default mode of set, since that is advantageous
for dumping images on the screen.  All of the line drawing functions
take arguments in units of raster points.  The raster is 454 lines high
with 576 bits per line and the origin is at the lower left corner of the
TV screen.  All routines return one if the requested operation could be
performed, and zero otherwise.  Note that in all cases, the specified
operation will not be performed if it would result in movement off of
the screen.  The routine testp is the only plotting function that does
not return 0 if the point is off of the screen or the TV could not be
opened.

	point(x, y)	Draw dot at the raster point (x, y).  Returns
			0 if the point was not on the screen or the TV
			could not be opened, otherwise returns 1.

	testp(x, y)	Returns 1, if the indicated point is set,
			0, if the indicated point is clear, and
			-1, if the indicated point is off the screen or
			if the TV could not be opened.

	line(x0, 01, y1, y1)
			Draw a line from (x0, y0) to (x1, y1).  Returns
			0 is either point is off the screen or if the TV
			mapping could not be established, otherwise
			returns 1.

	connect(x, y)	Draws a line from the last point drawn to the
			indicated point.  Returns 1, if the new point lies
			on the screen and the line could be drawn, 0 otherwise.

	move(x, y)	Move to (x, y) without drawing anything.  It
			does not open the TV if it is closed.  Move
			returns 0 if the point is off of the screen, and
			returns 1 otherwise. 

	circle(x, y, r)	Draw a circle of radius r, centered at (x, y).
			Returns 1, if the circle is inside the screen and
			was successfully drawn, otherwise returns 0.

	tvwrite(line, word, data)
			Write the 32 rightmost bits of the supplied data
			to the indicated line and word of the TV buffer.
			If necessary, the TV is opened and the mode is
			changed to SET mode.  The routine checks for out
			of bounds line and word arguments.  Returns 1,
			unless the write could not be performed.


The following routines are not usually used by casual users since the
graphics primitives described above initialize the state of the TV.


	tvopen()       	Map PDP-10 memory onto PDP-11 memory.
			A pointer to the beginning of the TV array is
		      	returned, but this pointer may be ignored by
		       	the caller, since the package uses its own copy
		       	of the TV array pointer.  A return code of 0
		       	indicates failure.

	tvclose()	Undo the mapping and release the memory used
		      	by the TV array.  No value is returned and no
			action is taken if the TV is not open.

	tvmode(mode)	Change the mode by which updates to the TV 
			buffer are affected.  Useful modes are defined
			as macro variables in CLIB;TV H.  The previous
			mode is returned.

	tvclear()	Clear the screen.  The cursor is moved to the
			lower left corner of the screen.  The request is
			ignored if the TV is not open and no value is
			returned.

	tvbase()	Return the value of the TV pointer.  The TV pointer
			is always 0 if the TV memory is not mapped into
			the program address space.

	tvsetup()	Open TV, clear the screen, and set the TV mode
			to inclusive-OR mode.  A pointer to the TV buffer
			is returned or 0 if the TV could not be opened.


The source for all of these routines is in CLIB;TV C.  These routines
are not part of the Shared Library.

For information on the algorithms used in this graphics package,
consult

  	B. K. P. Horn, "Circle Generators for Display Devices",
	Computer Graphics and Image Processing 5, 280-288 (1976).


Node: Image Files, Previous: TV Graphics, Up: Graphics, Next: Graphics



Node: Miscellaneous, Previous: Basics, Up: Top, Next: Internals


This node documents some assorted routines that perform various
interesting and useful functions that do not fit into the taxonomy for
the rest of the C documentation.

CLIB;C10EXP C	Contains a routine for expanding an argument vector that
		contains filenames with wild characters.

CLIB;C10FD  C	Contains FDMAP(P,F) which calls the procedure F(S) for
		all filenames S that match a pattern P.  This source
		file also contains some routines for working with
		directories.

CLIB;C10FIL C	Contains RENAME(S1,S2) which renames file S1 to S2 and
		is claimed to work even if S2 exists.

CLIB;C10FNM C	Contains routines for manipulating filenames.

CLIB;C10STD C	Contains interface routines for implementing the
		functions of the Standard I/O Library using functions in
		the Portable I/O Library.

CLIB;APFNAM C	Contains some routines for appending suffixes to
		filenames.

CLIB;GETSRV C	Contains a routine for looking up ARPA net servers.

CLIB;C10TAP CMID
	Contains a magtape interface.


Node: Internals, Previous: Basics, Up: Top, Next: Top



---LOCAL Modes:---
---Mode: Text---
---Fill Column:72---
---Auto Fill Mode: 1---
---End:--